@ix-xs/node-comfort 1.2.0 → 2.0.0

package/types/src/Http.d.ts

@@ -0,0 +1,374 @@
+declare namespace _exports {
+    export { HttpBody, HttpMethod, QueryParams, HttpRetryOptions, HttpRequestConfig, HttpHooks, HttpOptions, HttpResponse, HttpClient };
+}
+declare namespace _exports {
+    export { request };
+    export { get };
+    export { head };
+    export { post };
+    export { put };
+    export { patch };
+    export { del as delete };
+    export { download };
+    export { create };
+    export { HttpError };
+}
+export = _exports;
+/**
+ * A request body.
+ */
+type HttpBody = string | Buffer | Uint8Array | ArrayBuffer | URLSearchParams | FormData | Blob | ReadableStream | import("node:stream").Readable;
+/**
+ * An HTTP method.
+ */
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | (string & {});
+/**
+ * Query string values. `null` and `undefined` are skipped, arrays repeat the key.
+ */
+type QueryParams = Record<string, string | number | boolean | null | undefined | Array<string | number | boolean>>;
+/**
+ * Retry settings.
+ */
+type HttpRetryOptions = {
+    /**
+     * Total attempts, the first included. Defaults to `3` for methods that are safe to repeat, `1` for the others.
+     */
+    attempts?: number | undefined;
+    /**
+     * Wait before the first retry, in ms. Defaults to `300`.
+     */
+    delay?: number | undefined;
+    /**
+     * Multiplies the wait after each attempt. Defaults to `2`.
+     */
+    backoff?: number | undefined;
+    /**
+     * Longest wait, `Retry-After` included. Defaults to 30 seconds.
+     */
+    maxDelay?: number | undefined;
+    /**
+     * Statuses worth retrying. Defaults to 408, 413, 429, 500, 502, 503 and 504.
+     */
+    statuses?: number[] | undefined;
+    /**
+     * Methods allowed to retry. POST and PATCH aren't, by default, so nothing gets created twice.
+     */
+    methods?: HttpMethod[] | undefined;
+};
+/**
+ * A request as hooks see it.
+ */
+type HttpRequestConfig = {
+    /**
+     * The final URL, base URL and query included.
+     */
+    url: string;
+    method: HttpMethod;
+    /**
+     * Lower-cased names.
+     */
+    headers: Record<string, string>;
+    body: HttpBody | undefined;
+    /**
+     * 1 for the first try.
+     */
+    attempt: number;
+};
+/**
+ * Hooks to watch or change requests.
+ */
+type HttpHooks = {
+    /**
+     * Runs before each attempt. It can change the URL, headers or body.
+     */
+    beforeRequest?: ((config: HttpRequestConfig) => void | Promise<void>)[] | undefined;
+    /**
+     * Runs after each response, before errors are thrown. It can return another response.
+     */
+    afterResponse?: ((response: HttpResponse<any>, config: HttpRequestConfig) => void | HttpResponse<any> | Promise<void | HttpResponse<any>>)[] | undefined;
+    /**
+     * Runs before waiting for a retry.
+     */
+    beforeRetry?: ((error: unknown, attempt: number, delay: number) => void | Promise<void>)[] | undefined;
+};
+/**
+ * Request options.
+ */
+type HttpOptions = {
+    /**
+     * Defaults to `"GET"`.
+     */
+    method?: HttpMethod | undefined;
+    /**
+     * Prefix for relative URLs.
+     */
+    baseURL?: string | undefined;
+    /**
+     * Set a header to `undefined` to remove a default one.
+     */
+    headers?: Record<string, string | undefined> | undefined;
+    /**
+     * Added to the URL's own query string.
+     */
+    query?: URLSearchParams | QueryParams | undefined;
+    /**
+     * Sent as JSON.
+     */
+    json?: unknown;
+    /**
+     * Sent as a URL-encoded form.
+     */
+    form?: Record<string, string | number | boolean> | undefined;
+    /**
+     * Sent as is: string, Buffer, `FormData`, stream...
+     */
+    body?: HttpBody | undefined;
+    /**
+     * Sets the `authorization` header.
+     */
+    auth?: {
+        bearer: string;
+    } | {
+        username: string;
+        password: string;
+    } | undefined;
+    /**
+     * Time limit per attempt, like `"10s"`. `false` turns it off. Defaults to 30 seconds.
+     */
+    timeout?: string | number | false | undefined;
+    /**
+     * Number of attempts, `false`, or retry settings.
+     */
+    retry?: number | false | HttpRetryOptions | undefined;
+    /**
+     * How to read the body. `"auto"` reads JSON or text based on the content type, a Buffer otherwise.
+     */
+    responseType?: "auto" | "json" | "buffer" | "text" | "stream" | undefined;
+    /**
+     * Throw an `HttpError` when the status isn't 2xx. Defaults to `true`.
+     */
+    throwHttpErrors?: boolean | undefined;
+    /**
+     * Cancels the request.
+     */
+    signal?: AbortSignal | undefined;
+    hooks?: HttpHooks | undefined;
+    /**
+     * Called while the body downloads.
+     */
+    onDownloadProgress?: ((progress: {
+        loaded: number;
+        total: number | undefined;
+        percent: number | undefined;
+    }) => void) | undefined;
+    /**
+     * Defaults to `"follow"`.
+     */
+    redirect?: "error" | "follow" | "manual" | undefined;
+};
+/**
+ * A response.
+ */
+type HttpResponse<T = any> = {
+    status: number;
+    statusText: string;
+    /**
+     * `true` for 2xx statuses.
+     */
+    ok: boolean;
+    /**
+     * Lower-cased names.
+     */
+    headers: Record<string, string>;
+    /**
+     * The body, already read (see `responseType`).
+     */
+    data: T;
+    /**
+     * The final URL, after redirects.
+     */
+    url: string;
+    /**
+     * In ms, retries included.
+     */
+    duration: number;
+    /**
+     * How many attempts it took.
+     */
+    attempts: number;
+};
+/**
+ * A client with its own defaults, from `create()`.
+ */
+type HttpClient = {
+    /**
+     * Sends a request.
+     */
+    request: <T = any>(url: string | URL, options?: HttpOptions) => Promise<HttpResponse<T>>;
+    /**
+     * Sends a GET request.
+     */
+    get: <T = any>(url: string | URL, options?: HttpOptions) => Promise<HttpResponse<T>>;
+    /**
+     * Sends a HEAD request.
+     */
+    head: <T = any>(url: string | URL, options?: HttpOptions) => Promise<HttpResponse<T>>;
+    /**
+     * Sends a DELETE request.
+     */
+    delete: <T = any>(url: string | URL, options?: HttpOptions) => Promise<HttpResponse<T>>;
+    /**
+     * Sends a POST request. Objects and arrays go as JSON.
+     */
+    post: <T = any>(url: string | URL, data?: unknown, options?: HttpOptions) => Promise<HttpResponse<T>>;
+    /**
+     * Sends a PUT request. Objects and arrays go as JSON.
+     */
+    put: <T = any>(url: string | URL, data?: unknown, options?: HttpOptions) => Promise<HttpResponse<T>>;
+    /**
+     * Sends a PATCH request. Objects and arrays go as JSON.
+     */
+    patch: <T = any>(url: string | URL, data?: unknown, options?: HttpOptions) => Promise<HttpResponse<T>>;
+    /**
+     * Saves a response to a file.
+     */
+    download: (url: string | URL, destination: string, options?: HttpOptions) => Promise<{
+        path: string;
+        size: number;
+    }>;
+    /**
+     * A new client with these defaults added.
+     */
+    extend: (defaults: HttpOptions) => HttpClient;
+    defaults: Readonly<HttpOptions>;
+};
+/**
+ * Sends a request and resolves with the response, body already read.
+ * Throws an `HttpError` for error statuses, a `TimeoutError` when it's too
+ * slow and an `AbortError` when cancelled.
+ *
+ * @example
+ * const res = await http.request("https://api.example.com/items/42", {
+ *   method: "PUT",
+ *   json: { name: "Lamp" },
+ *   timeout: "10s",
+ *   retry: { attempts: 5, statuses: [429, 503] },
+ * });
+ * res.data; // parsed JSON
+ *
+ * @template [T=any]
+ * @param {string | URL} url An absolute URL, or a path when `baseURL` is set.
+ * @param {HttpOptions} [options]
+ * @returns {Promise<HttpResponse<T>>}
+ * @throws {HttpError | TimeoutError | AbortError}
+ */
+declare function request<T = any>(url: string | URL, options?: HttpOptions): Promise<HttpResponse<T>>;
+/**
+ * Sends a GET request.
+ *
+ * @example
+ * const { data } = await http.get("https://api.example.com/users", { query: { page: 2, tags: ["a", "b"] } });
+ *
+ * @template [T=any]
+ * @param {string | URL} url
+ * @param {HttpOptions} [options]
+ * @returns {Promise<HttpResponse<T>>}
+ */
+declare function get<T = any>(url: string | URL, options?: HttpOptions): Promise<HttpResponse<T>>;
+/**
+ * Sends a HEAD request: headers only, no body.
+ *
+ * @example
+ * const { headers } = await http.head("https://example.com/big.zip");
+ * headers["content-length"];
+ *
+ * @template [T=undefined]
+ * @param {string | URL} url
+ * @param {HttpOptions} [options]
+ * @returns {Promise<HttpResponse<T>>}
+ */
+declare function head<T = undefined>(url: string | URL, options?: HttpOptions): Promise<HttpResponse<T>>;
+/**
+ * Sends a POST request. Objects, arrays, numbers and booleans go as JSON;
+ * strings, Buffers, `FormData`, Blobs and streams go as they are.
+ *
+ * @example
+ * const { data: user } = await http.post("https://api.example.com/users", { name: "Ada" });
+ * await http.post(uploadUrl, formData);
+ *
+ * @template [T=any]
+ * @param {string | URL} url
+ * @param {unknown} [data]
+ * @param {HttpOptions} [options]
+ * @returns {Promise<HttpResponse<T>>}
+ */
+declare function post<T = any>(url: string | URL, data?: unknown, options?: HttpOptions): Promise<HttpResponse<T>>;
+/**
+ * Sends a PUT request. The body works like in `post()`.
+ *
+ * @template [T=any]
+ * @param {string | URL} url
+ * @param {unknown} [data]
+ * @param {HttpOptions} [options]
+ * @returns {Promise<HttpResponse<T>>}
+ */
+declare function put<T = any>(url: string | URL, data?: unknown, options?: HttpOptions): Promise<HttpResponse<T>>;
+/**
+ * Sends a PATCH request. The body works like in `post()`.
+ *
+ * @template [T=any]
+ * @param {string | URL} url
+ * @param {unknown} [data]
+ * @param {HttpOptions} [options]
+ * @returns {Promise<HttpResponse<T>>}
+ */
+declare function patch<T = any>(url: string | URL, data?: unknown, options?: HttpOptions): Promise<HttpResponse<T>>;
+/**
+ * Sends a DELETE request.
+ *
+ * @example
+ * await http.delete(`https://api.example.com/users/${id}`);
+ *
+ * @template [T=any]
+ * @param {string | URL} url
+ * @param {HttpOptions} [options]
+ * @returns {Promise<HttpResponse<T>>}
+ */
+declare function del<T = any>(url: string | URL, options?: HttpOptions): Promise<HttpResponse<T>>;
+/**
+ * Downloads to a file as a stream, so memory stays flat whatever the size.
+ * Folders are created, and a partial file is removed if it fails.
+ *
+ * @example
+ * await http.download("https://example.com/video.mp4", "./downloads/video.mp4", {
+ *   onDownloadProgress: ({ percent }) => bar.update(percent ?? 0),
+ * });
+ *
+ * @param {string | URL} url
+ * @param {string} destination
+ * @param {HttpOptions} [options]
+ * @returns {Promise<{ path: string, size: number }>} The absolute path and size in bytes.
+ * @throws {HttpError | TimeoutError | AbortError}
+ */
+declare function download(url: string | URL, destination: string, options?: HttpOptions): Promise<{
+    path: string;
+    size: number;
+}>;
+/**
+ * Creates a client with default options. Options passed to each call are
+ * merged on top.
+ *
+ * @example
+ * const github = http.create({
+ *   baseURL: "https://api.github.com",
+ *   auth: { bearer: process.env.GITHUB_TOKEN },
+ *   hooks: { afterResponse: [(res) => nc.debug(res.status, res.url)] },
+ * });
+ * const { data: repo } = await github.get("/repos/nodejs/node");
+ *
+ * @param {HttpOptions} [defaults]
+ * @returns {HttpClient}
+ */
+declare function create(defaults?: HttpOptions): HttpClient;
+import { HttpError } from "./errors.js";
+//# sourceMappingURL=Http.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Http.d.ts","sourceRoot":"","sources":["../../src/Http.js"],"names":[],"mappings":"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"}

package/types/src/Id.d.ts

@@ -1,119 +1,200 @@
 /**
- * Generates a random UUID v4.
+ * Encodings for `token()`.
+ */
+export type TokenEncoding = "hex" | "base64" | "base64url" | "base58" | "base32";
+/**
+ * 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).
- *
- * Uses secure randomness with unbiased rejection sampling.
+ * 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.
  *
  * @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.
- *
- * ULIDs sort by creation time and are a great primary-key alternative to UUIDs.
+ * A ULID: 26 URL-safe characters that sort by creation time. Ids made in
+ * the same millisecond still increase.
  *
  * @example
- * nodeComfort.id.ulid(); // "01ARZ3NDEKTSV4RRFFQ69G5FAV"
+ * id.ulid();                       // "01HQ3Z8K9V3N5W7Y2XJ4T6R8PB"
+ * id.ulid(Date.UTC(2024, 0, 1));   // for a given time
  *
- * @param {number} [time=Date.now()] - Timestamp in ms to encode.
- * @returns {string} A 26-character ULID.
+ * @param {number} [time] Timestamp to encode, in ms. Defaults to now.
+ * @returns {string}
  */
 export function ulid(time?: number): 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).
- *
- * Ambiguous characters (`0/O`, `1/I`) are excluded, making it suitable for
- * coupons, OTP-like codes and invite links.
+ * Makes an id generator with your own alphabet and length.
  *
  * @example
- * nodeComfort.id.code();            // "K7QF9X"
- * nodeComfort.id.code(4, "1234");   // "3142"
+ * const orderId = id.customAlphabet("0123456789ABCDEF", 12);
+ * orderId(); // "4F1A09C2BB7E"
  *
- * @param {number} [length=6] - Number of characters.
- * @param {string} [alphabet="ABCDEFGHJKLMNPQRSTUVWXYZ23456789"] - Characters to pick from.
- * @returns {string} The random code.
+ * @param {string} alphabet
+ * @param {number} [size=21]
+ * @returns {(size?: number) => string}
  */
-export function code(length?: number, alphabet?: string): string;
+export function customAlphabet(alphabet: string, size?: number): (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}
+ */
+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}
  */
-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 ULID or a UUID v7 was created.
+ *
+ * @example
+ * id.timestamp(id.ulid()); // now
+ * id.timestamp(id.uuid()); // undefined, v4 has no time in it
  *
- * Useful for readable, unique keys within a single process run.
+ * @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;;;;;;;;;;;;;;;;;;;;;;;;;UAcnD,IAAI;;;;eACJ,MAAM;cACN,MAAM;eACN,MAAM;;;;eACN,MAAM;;AA8EpB;;;;;;;GAOG;AACH,wBAFa,MAAM,CAIlB;AAKD;;;;;;;;;;;GAWG;AACH,0BAFa,MAAM,CAsBlB;AAMD;;;;;;;;;;GAUG;AACH,4BAHW,MAAM,GACJ,MAAM,CA0BlB;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;;;;;;;;;;;GAWG;AACH,8BAJW,MAAM,aACN,aAAa,GACX,MAAM,CAOlB;AAED;;;;;;;;;;;GAWG;AACH,8BAJW,MAAM,aACN,MAAM,GACJ,MAAM,CAIlB;AAKD;;;;;;;;;GASG;AACH,oCAHW,gBAAgB,GACd,MAAM,CAgBlB;AAED;;;;;;;;;GASG;AACH,mCAJW,MAAM,GAAG,MAAM,YACf,gBAAgB,GACd,eAAe,CAY3B;AAED;;;;;;;;;GASG;AACH,iCAHW,MAAM,GACJ,IAAI,GAAG,SAAS,CAa5B;AAED;;;;;;;;;;GAUG;AACH,6BAHW,MAAM,GACJ,MAAM,CAKlB;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"}