@ix-xs/node-comfort 1.1.3 → 1.2.0

package/types/src/SQLite.d.ts

@@ -0,0 +1,396 @@
+export = SQLite;
+declare class SQLite {
+    /**
+     * Creates a new SQLite database connection.
+     *
+     * The database file and its parent folders are created if necessary.
+     * WAL journal mode and foreign key support are enabled automatically.
+     *
+     * Pass `":memory:"` to create a transient in-memory database.
+     *
+     * @param {string} [path="db.sqlite"] - Path to the SQLite database file.
+     *
+     * @example
+     * const db = new SQLite();
+     *
+     * @example
+     * const db = new SQLite("data/my-app.sqlite");
+     *
+     * @example
+     * const db = new SQLite(":memory:");
+     */
+    constructor(path?: string);
+    /**
+     * Executes a raw SQL statement using `run()`.
+     *
+     * Use this for custom SQL that is not covered by the helper methods.
+     * This method is intended for statements such as:
+     * - `INSERT`
+     * - `UPDATE`
+     * - `DELETE`
+     * - `CREATE INDEX`
+     * - PRAGMA writes
+     *
+     * @param {string} sql - SQL statement.
+     * @param {any[]|any} [params=[]] - Parameters to bind.
+     * @returns {Promise<{ changes: number, lastInsertRowid: bigint|number } | { error: string }>}
+     */
+    exec(sql: string, params?: any[] | any): Promise<{
+        changes: number;
+        lastInsertRowid: bigint | number;
+    } | {
+        error: string;
+    }>;
+    /**
+     * Executes a raw SQL query and returns the first row.
+     *
+     * @param {string} sql - SQL query.
+     * @param {any[]|any} [params=[]] - Parameters to bind.
+     * @returns {Promise<object|undefined|{ error: string }>}
+     */
+    queryOne(sql: string, params?: any[] | any): Promise<object | undefined | {
+        error: string;
+    }>;
+    /**
+     * Executes a raw SQL query and returns all rows.
+     *
+     * @param {string} sql - SQL query.
+     * @param {any[]|any} [params=[]] - Parameters to bind.
+     * @returns {Promise<object[]|{ error: string }>}
+     */
+    queryAll(sql: string, params?: any[] | any): Promise<object[] | {
+        error: string;
+    }>;
+    /**
+     * Creates a table and stores its schema in memory.
+     *
+     * This method supports both the new `columns` property and the legacy
+     * `options` property for backward compatibility.
+     *
+     * @param {{
+     *   name: string,
+     *   columns?: Record<string, {
+     *     type: "INTEGER"|"TEXT"|"REAL"|"BLOB"|"NUMERIC",
+     *     primaryKey?: boolean,
+     *     autoincrement?: boolean,
+     *     notNull?: boolean,
+     *     unique?: boolean,
+     *     defaultValue?: any,
+     *     values?: any[],
+     *     references?: { table: string, column: string },
+     *     onDelete?: string,
+     *     onUpdate?: string
+     *   }>,
+     *   options?: Record<string, any>,
+     *   constraints?: Array<
+     *     | { type: "unique", columns: string[] }
+     *     | { type: "primaryKey", columns: string[] }
+     *     | { type: "check", expression: string }
+     *     | {
+     *         type: "foreignKey",
+     *         columns: string[],
+     *         references: { table: string, columns: string[] },
+     *         onDelete?: string,
+     *         onUpdate?: string
+     *       }
+     *   >,
+     *   indexes?: Array<{
+     *     name?: string,
+     *     columns: string[],
+     *     unique?: boolean
+     *   }>
+     * }} table - Table definition.
+     * @returns {Promise<{ ok: true } | { error: string }>}
+     *
+     * @example
+     * await db.createTable({
+     *   name: "Post",
+     *   columns: {
+     *     id: { type: "INTEGER", primaryKey: true, autoincrement: true },
+     *     userId: {
+     *       type: "INTEGER",
+     *       notNull: true,
+     *       references: { table: "User", column: "id" },
+     *       onDelete: "CASCADE"
+     *     },
+     *     title: { type: "TEXT", notNull: true }
+     *   },
+     *   indexes: [{ columns: ["userId"] }]
+     * });
+     */
+    createTable(table: {
+        name: string;
+        columns?: Record<string, {
+            type: "INTEGER" | "TEXT" | "REAL" | "BLOB" | "NUMERIC";
+            primaryKey?: boolean;
+            autoincrement?: boolean;
+            notNull?: boolean;
+            unique?: boolean;
+            defaultValue?: any;
+            values?: any[];
+            references?: {
+                table: string;
+                column: string;
+            };
+            onDelete?: string;
+            onUpdate?: string;
+        }>;
+        options?: Record<string, any>;
+        constraints?: Array<{
+            type: "unique";
+            columns: string[];
+        } | {
+            type: "primaryKey";
+            columns: string[];
+        } | {
+            type: "check";
+            expression: string;
+        } | {
+            type: "foreignKey";
+            columns: string[];
+            references: {
+                table: string;
+                columns: string[];
+            };
+            onDelete?: string;
+            onUpdate?: string;
+        }>;
+        indexes?: Array<{
+            name?: string;
+            columns: string[];
+            unique?: boolean;
+        }>;
+    }): Promise<{
+        ok: true;
+    } | {
+        error: string;
+    }>;
+    /**
+     * Creates an index on an existing table.
+     *
+     * Composite indexes are supported by passing multiple columns.
+     *
+     * @param {string} tableName - Table name.
+     * @param {{
+     *   name?: string,
+     *   columns: string[],
+     *   unique?: boolean
+     * }} index - Index definition.
+     * @returns {Promise<{ ok: true } | { error: string }>}
+     *
+     * @example
+     * await db.createIndex("UserAuthMethod", {
+     *   columns: ["provider", "providerUserId"],
+     *   unique: true
+     * });
+     */
+    createIndex(tableName: string, index: {
+        name?: string;
+        columns: string[];
+        unique?: boolean;
+    }): Promise<{
+        ok: true;
+    } | {
+        error: string;
+    }>;
+    /**
+     * Drops a table and removes its model definition.
+     *
+     * @param {string} tableName - Table name.
+     * @returns {Promise<{ ok: true } | { error: string }>}
+     */
+    deleteTable(tableName: string): Promise<{
+        ok: true;
+    } | {
+        error: string;
+    }>;
+    /**
+     * Deletes all rows from a table.
+     *
+     * @param {string} tableName - Table name.
+     * @returns {Promise<{ ok: true } | { error: string }>}
+     */
+    clearTable(tableName: string): Promise<{
+        ok: true;
+    } | {
+        error: string;
+    }>;
+    /**
+     * Returns a single row matching a plain-object WHERE clause.
+     *
+     * @param {string} tableName - Table name.
+     * @param {Record<string, any>} [where={}] - Conditions.
+     * @returns {Promise<object|undefined|{ error: string }>}
+     */
+    get(tableName: string, where?: Record<string, any>): Promise<object | undefined | {
+        error: string;
+    }>;
+    /**
+     * Returns multiple rows from a table.
+     *
+     * Supports:
+     * - exact-match filters via `where`
+     * - custom ordering
+     * - pagination via `limit` and `offset`
+     *
+     * @param {string} tableName - Table name.
+     * @param {Record<string, any>} [where={}] - Exact-match conditions.
+     * @param {{
+     *   limit?: number,
+     *   offset?: number,
+     *   orderBy?: string,
+     *   direction?: "ASC"|"DESC"
+     * }} [options={}] - Query options.
+     * @returns {Promise<object[] | { error: string }>}
+     *
+     * @example
+     * const posts = await db.getAll("Post", { userId: 1 }, {
+     *   limit: 20,
+     *   offset: 0,
+     *   orderBy: "createdAt",
+     *   direction: "DESC"
+     * });
+     */
+    getAll(tableName: string, where?: Record<string, any>, options?: {
+        limit?: number;
+        offset?: number;
+        orderBy?: string;
+        direction?: "ASC" | "DESC";
+    }): Promise<object[] | {
+        error: string;
+    }>;
+    /**
+     * Inserts a new row into a table.
+     *
+     * This method performs a plain `INSERT`.
+     * If a unique constraint is violated, SQLite will throw an error.
+     *
+     * @param {string} tableName - Table name.
+     * @param {Record<string, any>} data - Row to insert.
+     * @returns {Promise<{ ok: true, lastInsertRowid: bigint|number, changes: number } | { error: string }>}
+     */
+    insert(tableName: string, data: Record<string, any>): Promise<{
+        ok: true;
+        lastInsertRowid: bigint | number;
+        changes: number;
+    } | {
+        error: string;
+    }>;
+    /**
+     * Updates one or more rows matching a WHERE clause.
+     *
+     * This method performs a plain `UPDATE`.
+     *
+     * @param {string} tableName - Table name.
+     * @param {Record<string, any>} data - Fields to update.
+     * @param {Record<string, any>} where - Conditions used to select rows.
+     * @returns {Promise<{ ok: true, changes: number } | { error: string }>}
+     */
+    update(tableName: string, data: Record<string, any>, where: Record<string, any>): Promise<{
+        ok: true;
+        changes: number;
+    } | {
+        error: string;
+    }>;
+    /**
+     * Inserts or updates a row using SQLite `ON CONFLICT DO UPDATE`.
+     *
+     * This is safer than `INSERT OR REPLACE` because it does not delete
+     * and recreate the row.
+     *
+     * @param {string} tableName - Table name.
+     * @param {Record<string, any>} data - Row data.
+     * @param {string[]} conflict - Columns that define the conflict target.
+     * @returns {Promise<{ ok: true, changes: number, lastInsertRowid: bigint|number } | { error: string }>}
+     *
+     * @example
+     * await db.upsert("UserAuthMethod", {
+     *   userId: 1,
+     *   provider: "google",
+     *   providerUserId: "123"
+     * }, ["provider", "providerUserId"]);
+     */
+    upsert(tableName: string, data: Record<string, any>, conflict?: string[]): Promise<{
+        ok: true;
+        changes: number;
+        lastInsertRowid: bigint | number;
+    } | {
+        error: string;
+    }>;
+    /**
+     * Backward-compatible helper that inserts or updates a row.
+     *
+     * Behavior:
+     * - If `where` is provided, the existing row is loaded and merged with `data`,
+     *   then updated if found or inserted if not found.
+     * - If `where` is not provided but `data.id` exists, lookup is performed on `id`.
+     * - If no existing row is found, a new row is inserted.
+     *
+     * This method is intentionally simple, but for production-grade control,
+     * prefer using `insert()`, `update()`, or `upsert()`.
+     *
+     * @param {string} tableName - Table name.
+     * @param {Record<string, any>} data - Row data.
+     * @param {Record<string, any>|null} [where=null] - Lookup condition.
+     * @returns {Promise<{ ok: true } | { error: string }>}
+     */
+    set(tableName: string, data: Record<string, any>, where?: Record<string, any> | null): Promise<{
+        ok: true;
+    } | {
+        error: string;
+    }>;
+    /**
+     * Deletes rows matching a WHERE clause.
+     *
+     * @param {string} tableName - Table name.
+     * @param {Record<string, any>} where - Conditions.
+     * @returns {Promise<{ ok: true, changes: number } | { error: string }>}
+     */
+    delete(tableName: string, where: Record<string, any>): Promise<{
+        ok: true;
+        changes: number;
+    } | {
+        error: string;
+    }>;
+    /**
+     * Counts rows matching a WHERE clause.
+     *
+     * @param {string} tableName - Table name.
+     * @param {Record<string, any>} [where={}] - Conditions.
+     * @returns {Promise<number | { error: string }>}
+     */
+    count(tableName: string, where?: Record<string, any>): Promise<number | {
+        error: string;
+    }>;
+    /**
+     * Runs multiple operations inside a transaction.
+     *
+     * If the callback throws, the transaction is rolled back.
+     * If the callback completes successfully, the transaction is committed.
+     *
+     * The callback may be synchronous or asynchronous.
+     *
+     * @template T
+     * @param {() => T|Promise<T>} callback - Function to execute inside the transaction.
+     * @returns {Promise<T | { error: string }>}
+     *
+     * @example
+     * const result = await db.transaction(async () => {
+     *   await db.insert("User", { email: "a@b.com", createdAt: Date.now() });
+     *   await db.insert("Profile", { userId: 1, nickname: "John" });
+     *   return { ok: true };
+     * });
+     */
+    transaction<T>(callback: () => T | Promise<T>): Promise<T | {
+        error: string;
+    }>;
+    /**
+     * Closes the underlying SQLite connection.
+     *
+     * @example
+     * db.close();
+     */
+    close(): void;
+    #private;
+}
+//# sourceMappingURL=SQLite.d.ts.map

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

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

package/types/src/Str.d.ts

@@ -0,0 +1,293 @@
+/**
+ * Capitalizes the first character of a string and lowercases the rest.
+ *
+ * @example
+ * nodeComfort.str.capitalize("hELLO"); // "Hello"
+ *
+ * @param {string} str - Input string.
+ * @returns {string} The capitalized string.
+ */
+export function capitalize(str: string): string;
+/**
+ * Uppercases the first character of each word (Title Case), leaving the rest untouched.
+ *
+ * @example
+ * nodeComfort.str.titleCase("the quick brown fox"); // "The Quick Brown Fox"
+ *
+ * @param {string} str - Input string.
+ * @returns {string} The title-cased string.
+ */
+export function titleCase(str: string): string;
+/**
+ * Converts a string to `camelCase`.
+ *
+ * @example
+ * nodeComfort.str.camelCase("hello world");  // "helloWorld"
+ * nodeComfort.str.camelCase("foo-bar_baz");  // "fooBarBaz"
+ *
+ * @param {string} str - Input string.
+ * @returns {string} The camelCased string.
+ */
+export function camelCase(str: string): string;
+/**
+ * Converts a string to `PascalCase`.
+ *
+ * @example
+ * nodeComfort.str.pascalCase("hello world"); // "HelloWorld"
+ *
+ * @param {string} str - Input string.
+ * @returns {string} The PascalCased string.
+ */
+export function pascalCase(str: string): string;
+/**
+ * Converts a string to `snake_case`.
+ *
+ * @example
+ * nodeComfort.str.snakeCase("helloWorld"); // "hello_world"
+ *
+ * @param {string} str - Input string.
+ * @returns {string} The snake_cased string.
+ */
+export function snakeCase(str: string): string;
+/**
+ * Converts a string to `kebab-case`.
+ *
+ * @example
+ * nodeComfort.str.kebabCase("helloWorld"); // "hello-world"
+ *
+ * @param {string} str - Input string.
+ * @returns {string} The kebab-cased string.
+ */
+export function kebabCase(str: string): string;
+/**
+ * Converts a string to `CONSTANT_CASE`.
+ *
+ * @example
+ * nodeComfort.str.constantCase("helloWorld"); // "HELLO_WORLD"
+ *
+ * @param {string} str - Input string.
+ * @returns {string} The CONSTANT_CASED string.
+ */
+export function constantCase(str: string): string;
+/**
+ * Converts a string into a URL-friendly slug.
+ *
+ * Accents/diacritics are stripped, non-alphanumeric runs become the separator.
+ *
+ * @example
+ * nodeComfort.str.slugify("Héllo, World!");            // "hello-world"
+ * nodeComfort.str.slugify("A B C", { separator: "_" }); // "a_b_c"
+ *
+ * @param {string} str - Input string.
+ * @param {{ separator?: string, lower?: boolean }} [options] - Slug options.
+ * @returns {string} The slug.
+ */
+export function slugify(str: string, options?: {
+    separator?: string;
+    lower?: boolean;
+}): string;
+/**
+ * Truncates a string to a maximum length, appending an ellipsis if cut.
+ *
+ * @example
+ * nodeComfort.str.truncate("Hello world", 8);                 // "Hello…"
+ * nodeComfort.str.truncate("Hello world", 8, { omission: "..." }); // "Hello..."
+ *
+ * @param {string} str - Input string.
+ * @param {number} length - Maximum length of the result (including the omission).
+ * @param {{ omission?: string, words?: boolean }} [options] - Truncation options.
+ * @returns {string} The truncated string.
+ */
+export function truncate(str: string, length: number, options?: {
+    omission?: string;
+    words?: boolean;
+}): string;
+/**
+ * Pads a string on the left (start) to a target length.
+ *
+ * @param {string} str - Input string.
+ * @param {number} length - Target total length.
+ * @param {string} [char=" "] - Padding character(s).
+ * @returns {string} The padded string.
+ */
+export function padStart(str: string, length: number, char?: string): string;
+/**
+ * Pads a string on the right (end) to a target length.
+ *
+ * @param {string} str - Input string.
+ * @param {number} length - Target total length.
+ * @param {string} [char=" "] - Padding character(s).
+ * @returns {string} The padded string.
+ */
+export function padEnd(str: string, length: number, char?: string): string;
+/**
+ * Centers a string within a target length by padding both sides.
+ *
+ * @example
+ * nodeComfort.str.center("hi", 6);        // "  hi  "
+ * nodeComfort.str.center("hi", 6, "*");   // "**hi**"
+ *
+ * @param {string} str - Input string.
+ * @param {number} length - Target total length.
+ * @param {string} [char=" "] - Padding character.
+ * @returns {string} The centered string.
+ */
+export function center(str: string, length: number, char?: string): string;
+/**
+ * Reverses a string (Unicode code-point aware, so emojis stay intact).
+ *
+ * @example
+ * nodeComfort.str.reverse("abc"); // "cba"
+ *
+ * @param {string} str - Input string.
+ * @returns {string} The reversed string.
+ */
+export function reverse(str: string): string;
+/**
+ * Collapses all runs of whitespace into single spaces and trims the ends.
+ *
+ * @example
+ * nodeComfort.str.squish("  hello   world \n"); // "hello world"
+ *
+ * @param {string} str - Input string.
+ * @returns {string} The normalized string.
+ */
+export function squish(str: string): string;
+/**
+ * Removes all HTML tags from a string.
+ *
+ * @example
+ * nodeComfort.str.stripTags("<b>Hi</b> there"); // "Hi there"
+ *
+ * @param {string} str - Input string.
+ * @returns {string} The string with tags removed.
+ */
+export function stripTags(str: string): string;
+/**
+ * Escapes HTML-sensitive characters (`& < > " '`).
+ *
+ * @example
+ * nodeComfort.str.escapeHTML('<a href="x">'); // "&lt;a href=&quot;x&quot;&gt;"
+ *
+ * @param {string} str - Input string.
+ * @returns {string} The escaped string.
+ */
+export function escapeHTML(str: string): string;
+/**
+ * Reverses {@link escapeHTML}: turns HTML entities back into characters.
+ *
+ * @param {string} str - Input string.
+ * @returns {string} The unescaped string.
+ */
+export function unescapeHTML(str: string): string;
+/**
+ * Escapes a string for safe use inside a `RegExp`.
+ *
+ * @example
+ * new RegExp(nodeComfort.str.escapeRegExp("a.b")); // matches literal "a.b"
+ *
+ * @param {string} str - Input string.
+ * @returns {string} The escaped string.
+ */
+export function escapeRegExp(str: string): string;
+/**
+ * Counts the number of non-overlapping occurrences of a substring.
+ *
+ * @example
+ * nodeComfort.str.count("banana", "a"); // 3
+ *
+ * @param {string} str - Input string.
+ * @param {string} sub - Substring to count.
+ * @returns {number} Number of occurrences.
+ */
+export function count(str: string, sub: string): number;
+/**
+ * Ensures a string starts with a given prefix (adds it only if missing).
+ *
+ * @example
+ * nodeComfort.str.ensurePrefix("example.com", "https://"); // "https://example.com"
+ *
+ * @param {string} str - Input string.
+ * @param {string} prefix - Prefix to ensure.
+ * @returns {string} The string with the prefix guaranteed.
+ */
+export function ensurePrefix(str: string, prefix: string): string;
+/**
+ * Ensures a string ends with a given suffix (adds it only if missing).
+ *
+ * @example
+ * nodeComfort.str.ensureSuffix("path", "/"); // "path/"
+ *
+ * @param {string} str - Input string.
+ * @param {string} suffix - Suffix to ensure.
+ * @returns {string} The string with the suffix guaranteed.
+ */
+export function ensureSuffix(str: string, suffix: string): string;
+/**
+ * Removes a prefix from a string if present.
+ *
+ * @param {string} str - Input string.
+ * @param {string} prefix - Prefix to remove.
+ * @returns {string} The string without the prefix.
+ */
+export function removePrefix(str: string, prefix: string): string;
+/**
+ * Removes a suffix from a string if present.
+ *
+ * @param {string} str - Input string.
+ * @param {string} suffix - Suffix to remove.
+ * @returns {string} The string without the suffix.
+ */
+export function removeSuffix(str: string, suffix: string): string;
+/**
+ * Renders a template, replacing `{key}` placeholders with values from `data`.
+ *
+ * Missing keys are left as-is by default. Nested paths (`{user.name}`) are supported.
+ *
+ * @example
+ * nodeComfort.str.template("Hi {name}, you have {count} msgs", { name: "Jo", count: 3 });
+ * // "Hi Jo, you have 3 msgs"
+ *
+ * @param {string} str - Template string.
+ * @param {Record<string, any>} data - Replacement values.
+ * @param {{ open?: string, close?: string, fallback?: string }} [options] - Delimiters / fallback.
+ * @returns {string} The rendered string.
+ */
+export function template(str: string, data: Record<string, any>, options?: {
+    open?: string;
+    close?: string;
+    fallback?: string;
+}): string;
+/**
+ * Splits a string into an array of "words" (camelCase / snake / kebab aware).
+ *
+ * @example
+ * nodeComfort.str.words("helloWorld-foo_bar"); // ["hello", "World", "foo", "bar"]
+ *
+ * @param {string} str - Input string.
+ * @returns {string[]} The words.
+ */
+export function words(str: string): string[];
+/**
+ * Returns the visible length of a string in code points (emoji-safe).
+ *
+ * @example
+ * "😀".length;                    // 2
+ * nodeComfort.str.length("😀");   // 1
+ *
+ * @param {string} str - Input string.
+ * @returns {number} The number of code points.
+ */
+export function length(str: string): number;
+/**
+ * Generates a random alphanumeric string of a given length.
+ *
+ * Note: uses `Math.random` and is **not** cryptographically secure.
+ * For tokens/IDs use `nodeComfort.id.token()` instead.
+ *
+ * @param {number} [length=16] - Desired length.
+ * @param {string} [charset] - Characters to pick from.
+ * @returns {string} The random string.
+ */
+export function random(length?: number, charset?: string): string;
+//# sourceMappingURL=Str.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Str.d.ts","sourceRoot":"","sources":["../../src/Str.js"],"names":[],"mappings":"AA2BE;;;;;;;;GAQG;AACH,gCAHW,MAAM,GACJ,MAAM,CAMlB;AAED;;;;;;;;GAQG;AACH,+BAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;GASG;AACH,+BAHW,MAAM,GACJ,MAAM,CAUlB;AAED;;;;;;;;GAQG;AACH,gCAHW,MAAM,GACJ,MAAM,CAMlB;AAED;;;;;;;;GAQG;AACH,+BAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;GAQG;AACH,+BAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;GAQG;AACH,kCAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;;;GAYG;AACH,6BAJW,MAAM,YACN;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACrC,MAAM,CAYlB;AAED;;;;;;;;;;;GAWG;AACH,8BALW,MAAM,UACN,MAAM,YACN;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GACpC,MAAM,CAelB;AAED;;;;;;;GAOG;AACH,8BALW,MAAM,UACN,MAAM,SACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;GAOG;AACH,4BALW,MAAM,UACN,MAAM,SACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;;GAWG;AACH,4BALW,MAAM,UACN,MAAM,SACN,MAAM,GACJ,MAAM,CASlB;AAED;;;;;;;;GAQG;AACH,6BAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;GAQG;AACH,4BAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;GAQG;AACH,+BAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;GAQG;AACH,gCAHW,MAAM,GACJ,MAAM,CAKlB;AAED;;;;;GAKG;AACH,kCAHW,MAAM,GACJ,MAAM,CAKlB;AAED;;;;;;;;GAQG;AACH,kCAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;GASG;AACH,2BAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAYlB;AAED;;;;;;;;;GASG;AACH,kCAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAKlB;AAED;;;;;;;;;GASG;AACH,kCAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAKlB;AAED;;;;;;GAMG;AACH,kCAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAKlB;AAED;;;;;;GAMG;AACH,kCAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAKlB;AAED;;;;;;;;;;;;;GAaG;AACH,8BALW,MAAM,QACN,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,YACnB;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAClD,MAAM,CAclB;AAED;;;;;;;;GAQG;AACH,2BAHW,MAAM,GACJ,MAAM,EAAE,CAIpB;AAED;;;;;;;;;GASG;AACH,4BAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;GASG;AACH,gCAJW,MAAM,YACN,MAAM,GACJ,MAAM,CAQlB"}