@ix-xs/node-comfort 1.2.0 → 2.1.0

package/types/src/Id.d.ts

@@ -1,119 +1,252 @@
 /**
- * Generates a random UUID v4.
+ * Encodings for `token()`.
+ */
+export type TokenEncoding = "hex" | "base64" | "base64url" | "base58" | "base32";
+/**
+ * A namespace for `uuidv5()`: one of the four standard ones, or any UUID of
+ * your own.
+ */
+export type UUIDNamespace = "dns" | "url" | "oid" | "x500" | (string & {});
+/**
+ * Options for `snowflake()` and `parseSnowflake()`.
+ */
+export type SnowflakeOptions = {
+    /**
+     * Start of time, in ms. Defaults to Discord's (2015-01-01). Twitter uses `1288834974657`.
+     */
+    epoch?: number | undefined;
+    /**
+     * 0 to 31. Defaults to `0`.
+     */
+    workerId?: number | undefined;
+    /**
+     * 0 to 31. Defaults to `process.pid % 32`.
+     */
+    processId?: number | undefined;
+};
+/**
+ * A decoded Snowflake.
+ */
+export type ParsedSnowflake = {
+    /**
+     * When it was created.
+     */
+    date: Date;
+    /**
+     * When it was created, in ms.
+     */
+    timestamp: number;
+    workerId: number;
+    processId: number;
+    /**
+     * Sequence number within the millisecond, 0 to 4095.
+     */
+    increment: number;
+};
+/**
+ * A random UUID (version 4). For ids that sort by date, see `uuidv7()`.
  *
  * @example
- * nodeComfort.id.uuid(); // "3f2504e0-4f89-41d3-9a0c-0305e82c3301"
+ * id.uuid(); // "3f2504e0-4f89-41d3-9a0c-0305e82c3301"
  *
- * @returns {string} A UUID v4 string.
+ * @returns {string}
  */
 export function uuid(): string;
 /**
- * Generates a URL-safe, collision-resistant ID (nanoid-compatible alphabet).
+ * A UUID v5: the same name in the same namespace always gives the same id.
+ * Use it to derive a stable id from something you already have, like a URL
+ * or an email, without storing a mapping.
  *
- * Uses secure randomness with unbiased rejection sampling.
+ * @example
+ * id.uuidv5("example.com", "dns");          // "cfbff0d1-9375-5685-968c-48ce8b15ae17", every time
+ * id.uuidv5("https://example.com/a", "url");
+ * id.uuidv5("ada@example.com", MY_APP_NAMESPACE); // any UUID works as a namespace
+ *
+ * @param {string | Buffer | Uint8Array} name
+ * @param {UUIDNamespace} namespace `"dns"`, `"url"`, `"oid"`, `"x500"` or a UUID.
+ * @returns {string}
+ */
+export function uuidv5(name: string | Buffer | Uint8Array, namespace: UUIDNamespace): string;
+/**
+ * A UUID v7: it starts with a timestamp, so ids sort by creation time.
+ * That keeps database indexes compact, which makes them great primary
+ * keys. Ids from the same process always increase, even within a
+ * millisecond, and even if the system clock steps back.
  *
  * @example
- * nodeComfort.id.nano();    // "V1StGXR8_Z5jdHi6B-myT"
- * nodeComfort.id.nano(10);  // "IRFa-VaY2b"
+ * id.uuidv7();               // "0190a5c4-7c1e-7b2a-9f3e-1c2d3e4f5a6b"
+ * id.timestamp(id.uuidv7()); // when it was created
  *
- * @param {number} [size=21] - Desired length.
- * @param {string} [alphabet] - Custom alphabet.
- * @returns {string} The generated ID.
+ * @returns {string}
  */
-export function nano(size?: number, alphabet?: string): string;
+export function uuidv7(): string;
 /**
- * Generates a ULID • a lexicographically-sortable, timestamp-prefixed ID.
+ * A ULID: 26 URL-safe characters that sort by creation time. Ids made in
+ * the same millisecond still increase.
  *
- * ULIDs sort by creation time and are a great primary-key alternative to UUIDs.
+ * @example
+ * id.ulid();                     // "01HQ3Z8K9V3N5W7Y2XJ4T6R8PB"
+ * id.ulid(Date.UTC(2024, 0, 1)); // for a given time
+ *
+ * @param {number | Date} [time] The moment to encode. Defaults to now.
+ * @returns {string}
+ * @throws {RangeError} If the time is not a valid timestamp.
+ */
+export function ulid(time?: number | Date): string;
+/**
+ * A MongoDB-style ObjectId: 24 hex characters that start with the time, in
+ * seconds, and increase within the process.
  *
  * @example
- * nodeComfort.id.ulid(); // "01ARZ3NDEKTSV4RRFFQ69G5FAV"
+ * id.objectId();                           // "65f2a9c47b1e4d0c9a3f2b10"
+ * id.timestamp(id.objectId());             // when it was created, to the second
+ * id.objectId(new Date("2024-01-01"));     // for a given time
  *
- * @param {number} [time=Date.now()] - Timestamp in ms to encode.
- * @returns {string} A 26-character ULID.
+ * @param {number | Date} [time] The moment to encode. Defaults to now.
+ * @returns {string}
+ * @throws {RangeError} If the time is not a valid timestamp.
  */
-export function ulid(time?: number): string;
+export function objectId(time?: number | Date): string;
 /**
- * Generates a cryptographically-secure random token.
+ * A short, URL-safe random id, like `nanoid`. At 21 characters, collisions
+ * are as unlikely as with a UUID.
  *
  * @example
- * nodeComfort.id.token();               // 32-byte hex string
- * nodeComfort.id.token(16, "base64url"); // 16 bytes, URL-safe base64
+ * id.nano();                      // "V1StGXR8_Z5jdHi6B-myT"
+ * id.nano(10);                    // "IRFa-VaY2b"
+ * id.nano(8, "0123456789abcdef"); // "4f90d13a"
  *
- * @param {number} [bytes=32] - Number of random bytes.
- * @param {"hex"|"base64"|"base64url"|"base58"} [encoding="hex"] - Output encoding.
- * @returns {string} The token.
+ * @param {number} [size=21]
+ * @param {string} [alphabet] 2 to 256 characters. Defaults to letters, digits, `_` and `-`.
+ * @returns {string}
  */
-export function token(bytes?: number, encoding?: "hex" | "base64" | "base64url" | "base58"): string;
+export function nano(size?: number, alphabet?: string): string;
 /**
- * Generates a short, human-friendly random code (uppercase + digits by default).
+ * Makes an id generator with your own alphabet and length.
  *
- * Ambiguous characters (`0/O`, `1/I`) are excluded, making it suitable for
- * coupons, OTP-like codes and invite links.
+ * @example
+ * const orderId = id.customAlphabet("0123456789ABCDEF", 12);
+ * orderId(); // "4F1A09C2BB7E"
+ *
+ * @param {string} alphabet
+ * @param {number} [size=21]
+ * @returns {(size?: number) => string}
+ */
+export function customAlphabet(alphabet: string, size?: number): (size?: number) => string;
+/**
+ * A random id with a prefix that says what it identifies, like Stripe's
+ * `cus_...` and `sub_...`. A glance at a log line or a support ticket tells
+ * you what kind of thing the id points to.
  *
  * @example
- * nodeComfort.id.code();            // "K7QF9X"
- * nodeComfort.id.code(4, "1234");   // "3142"
+ * id.prefixed("user");      // "user_7Hq2mXc0LrT9aZ4bWk1PdE8s"
+ * id.prefixed("inv", 12);   // "inv_Q0f8ZrT1bK4m"
  *
- * @param {number} [length=6] - Number of characters.
- * @param {string} [alphabet="ABCDEFGHJKLMNPQRSTUVWXYZ23456789"] - Characters to pick from.
- * @returns {string} The random code.
+ * @param {string} prefix
+ * @param {number} [size=24] How many random characters come after the prefix (letters and digits).
+ * @returns {string}
  */
-export function code(length?: number, alphabet?: string): string;
+export function prefixed(prefix: string, size?: number): string;
 /**
- * Hashes a value with a chosen algorithm.
+ * A random token for API keys, session ids, reset links...
  *
  * @example
- * nodeComfort.id.hash("hello");                  // sha256 hex
- * nodeComfort.id.hash("hello", { algorithm: "md5" });
+ * id.token();                // 64 hex characters
+ * id.token(16, "base64url"); // 22 URL-safe characters
+ * id.token(16, "base58");    // no look-alike characters
  *
- * @param {string|Buffer} value - Data to hash.
- * @param {{ algorithm?: string, encoding?: "hex"|"base64"|"base64url" }} [options] - Hash options.
- * @returns {string} The digest.
+ * @param {number} [bytes=32] How much randomness, in bytes.
+ * @param {TokenEncoding} [encoding="hex"]
+ * @returns {string}
  */
-export function hash(value: string | Buffer, options?: {
-    algorithm?: string;
-    encoding?: "hex" | "base64" | "base64url";
-}): string;
+export function token(bytes?: number, encoding?: TokenEncoding): string;
 /**
- * Computes an HMAC signature for a value using a secret key.
+ * A short code that's easy to read aloud and type: no `0/O` or `1/I/L`
+ * mix-ups. For invites, coupons and verification codes.
  *
  * @example
- * nodeComfort.id.hmac("payload", "secret"); // sha256 HMAC hex
+ * id.code();                // "K7QF9X"
+ * id.code(4, "0123456789"); // "3920"
  *
- * @param {string|Buffer} value - Data to sign.
- * @param {string|Buffer} secret - Secret key.
- * @param {{ algorithm?: string, encoding?: "hex"|"base64"|"base64url" }} [options] - HMAC options.
- * @returns {string} The signature.
+ * @param {number} [length=6]
+ * @param {string} [alphabet="ABCDEFGHJKMNPQRSTUVWXYZ23456789"]
+ * @returns {string}
  */
-export function hmac(value: string | Buffer, secret: string | Buffer, options?: {
-    algorithm?: string;
-    encoding?: "hex" | "base64" | "base64url";
-}): string;
+export function code(length?: number, alphabet?: string): string;
 /**
- * Compares two strings/buffers in constant time to prevent timing attacks.
+ * A Snowflake id, the 64-bit format used by Discord and Twitter. Returned
+ * as a string because it doesn't fit in a JavaScript number.
+ *
+ * @example
+ * id.snowflake(); // "1215361932810932224"
  *
- * Use this when comparing secrets, tokens, or signatures.
+ * @param {SnowflakeOptions} [options]
+ * @returns {string}
+ * @throws {RangeError} If the epoch is in the future.
+ */
+export function snowflake(options?: SnowflakeOptions): string;
+/**
+ * Decodes a Snowflake. With the default epoch, it reads Discord ids.
  *
  * @example
- * if (nodeComfort.id.safeEqual(provided, expected)) { ... }
+ * id.parseSnowflake("175928847299117063").date; // 2016-04-30T11:18:25.796Z
  *
- * @param {string|Buffer} a - First value.
- * @param {string|Buffer} b - Second value.
- * @returns {boolean} True if equal.
+ * @param {string | bigint} id
+ * @param {SnowflakeOptions} [options] Use the epoch it was created with.
+ * @returns {ParsedSnowflake}
+ * @throws {TypeError} If the id is not a string of digits or a bigint.
  */
-export function safeEqual(a: string | Buffer, b: string | Buffer): boolean;
+export function parseSnowflake(id: string | bigint, options?: SnowflakeOptions): ParsedSnowflake;
 /**
- * Returns a monotonically-increasing counter ID prefixed with an optional label.
+ * When a UUID v7, a ULID or an ObjectId was created.
  *
- * Useful for readable, unique keys within a single process run.
+ * @example
+ * id.timestamp(id.ulid());     // now
+ * id.timestamp(id.objectId()); // now, to the second
+ * id.timestamp(id.uuid());     // undefined, v4 has no time in it
+ *
+ * @param {string} value
+ * @returns {Date | undefined}
+ */
+export function timestamp(value: string): Date | undefined;
+/**
+ * Readable sequential ids like `"user-1"`, `"user-2"`, counted per prefix.
+ * Only unique within the current process; handy in logs and tests.
  *
  * @example
- * nodeComfort.id.seq("user"); // "user-1"
- * nodeComfort.id.seq("user"); // "user-2"
+ * id.seq("user"); // "user-1"
+ * id.seq("user"); // "user-2"
  *
- * @param {string} [prefix=""] - Optional prefix.
- * @returns {string} The sequential ID.
+ * @param {string} [prefix=""]
+ * @returns {string}
  */
 export function seq(prefix?: string): string;
+/**
+ * Hashes a value.
+ *
+ * @deprecated Use `nc.crypto.hash()`. This alias goes away in 3.0.
+ * @param {string | Buffer | Uint8Array} value
+ * @param {import("./Crypto").HashOptions} [options]
+ * @returns {string}
+ */
+export function hash(value: string | Buffer | Uint8Array, options?: import("./Crypto").HashOptions): string;
+/**
+ * Signs a value with HMAC.
+ *
+ * @deprecated Use `nc.crypto.hmac()`. This alias goes away in 3.0.
+ * @param {string | Buffer | Uint8Array} value
+ * @param {string | Buffer | Uint8Array} secret
+ * @param {import("./Crypto").HashOptions} [options]
+ * @returns {string}
+ */
+export function hmac(value: string | Buffer | Uint8Array, secret: string | Buffer | Uint8Array, options?: import("./Crypto").HashOptions): string;
+/**
+ * Compares two secrets in constant time.
+ *
+ * @deprecated Use `nc.crypto.safeEqual()`. This alias goes away in 3.0.
+ * @param {string | Buffer | Uint8Array} a
+ * @param {string | Buffer | Uint8Array} b
+ * @returns {boolean}
+ */
+export function safeEqual(a: string | Buffer | Uint8Array, b: string | Buffer | Uint8Array): boolean;
 //# sourceMappingURL=Id.d.ts.map

package/types/src/Id.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Id.d.ts","sourceRoot":"","sources":["../../src/Id.js"],"names":[],"mappings":"AAyDE;;;;;;;GAOG;AACH,wBAFa,MAAM,CAIlB;AAED;;;;;;;;;;;;GAYG;AACH,4BAJW,MAAM,aACN,MAAM,GACJ,MAAM,CAgBlB;AAED;;;;;;;;;;GAUG;AACH,4BAHW,MAAM,GACJ,MAAM,CAgBlB;AAED;;;;;;;;;;GAUG;AACH,8BAJW,MAAM,aACN,KAAK,GAAC,QAAQ,GAAC,WAAW,GAAC,QAAQ,GACjC,MAAM,CAMlB;AAED;;;;;;;;;;;;;GAaG;AACH,8BAJW,MAAM,aACN,MAAM,GACJ,MAAM,CASlB;AAED;;;;;;;;;;GAUG;AACH,4BAJW,MAAM,GAAC,MAAM,YACb;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,KAAK,GAAC,QAAQ,GAAC,WAAW,CAAA;CAAE,GAC3D,MAAM,CAMlB;AAED;;;;;;;;;;GAUG;AACH,4BALW,MAAM,GAAC,MAAM,UACb,MAAM,GAAC,MAAM,YACb;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,KAAK,GAAC,QAAQ,GAAC,WAAW,CAAA;CAAE,GAC3D,MAAM,CAMlB;AAED;;;;;;;;;;;GAWG;AACH,6BAJW,MAAM,GAAC,MAAM,KACb,MAAM,GAAC,MAAM,GACX,OAAO,CAOnB;AAED;;;;;;;;;;;GAWG;AACH,6BAHW,MAAM,GACJ,MAAM,CAKlB"}
+{"version":3,"file":"Id.d.ts","sourceRoot":"","sources":["../../src/Id.js"],"names":[],"mappings":";;;4BAqBa,KAAK,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ;;;;;4BAMpD,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;UAc7C,IAAI;;;;eACJ,MAAM;cACN,MAAM;eACN,MAAM;;;;eACN,MAAM;;AA4JpB;;;;;;;GAOG;AACH,wBAFa,MAAM,CAIlB;AAED;;;;;;;;;;;;;GAaG;AACH,6BAJW,MAAM,GAAG,MAAM,GAAG,UAAU,aAC5B,aAAa,GACX,MAAM,CAYlB;AAMD;;;;;;;;;;;GAWG;AACH,0BAFa,MAAM,CAmBlB;AAoBD;;;;;;;;;;;GAWG;AACH,4BAJW,MAAM,GAAG,IAAI,GACX,MAAM,CA6BlB;AAKD;;;;;;;;;;;;GAYG;AACH,gCAJW,MAAM,GAAG,IAAI,GACX,MAAM,CAalB;AAED;;;;;;;;;;;;GAYG;AACH,4BAJW,MAAM,aACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;GAUG;AACH,yCAJW,MAAM,SACN,MAAM,GACJ,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,MAAM,CAKrC;AAED;;;;;;;;;;;;GAYG;AACH,iCAJW,MAAM,SACN,MAAM,GACJ,MAAM,CAKlB;AAED;;;;;;;;;;;GAWG;AACH,8BAJW,MAAM,aACN,aAAa,GACX,MAAM,CASlB;AAED;;;;;;;;;;;GAWG;AACH,8BAJW,MAAM,aACN,MAAM,GACJ,MAAM,CAIlB;AAKD;;;;;;;;;;GAUG;AACH,oCAJW,gBAAgB,GACd,MAAM,CAiBlB;AAED;;;;;;;;;;GAUG;AACH,mCALW,MAAM,GAAG,MAAM,YACf,gBAAgB,GACd,eAAe,CAkB3B;AAED;;;;;;;;;;GAUG;AACH,iCAHW,MAAM,GACJ,IAAI,GAAG,SAAS,CAU5B;AAKD;;;;;;;;;;GAUG;AACH,6BAHW,MAAM,GACJ,MAAM,CAMlB;AAED;;;;;;;GAOG;AACH,4BAJW,MAAM,GAAG,MAAM,GAAG,UAAU,YAC5B,OAAO,UAAU,EAAE,WAAW,GAC5B,MAAM,CAIlB;AAED;;;;;;;;GAQG;AACH,4BALW,MAAM,GAAG,MAAM,GAAG,UAAU,UAC5B,MAAM,GAAG,MAAM,GAAG,UAAU,YAC5B,OAAO,UAAU,EAAE,WAAW,GAC5B,MAAM,CAIlB;AAED;;;;;;;GAOG;AACH,6BAJW,MAAM,GAAG,MAAM,GAAG,UAAU,KAC5B,MAAM,GAAG,MAAM,GAAG,UAAU,GAC1B,OAAO,CAInB"}