@cargo-ai/utils 1.0.4

package/build/src/poll.js

@@ -0,0 +1,30 @@
+import { clearIntervalAsync, setIntervalAsync } from "set-interval-async";
+export const pollOnInterval = async (fn, { intervalMs, maxPolls, }) => {
+    let intervalId;
+    const result = await new Promise((resolve) => {
+        let pollsCount = 1;
+        // See https://www.npmjs.com/package/set-interval-async#when-should-i-use-setintervalasync
+        intervalId = setIntervalAsync(async () => {
+            try {
+                const success = await fn();
+                if (success) {
+                    resolve(true);
+                }
+                else {
+                    if (pollsCount < maxPolls) {
+                        pollsCount++;
+                        return;
+                    }
+                    resolve(false);
+                }
+            }
+            catch {
+                resolve(false);
+            }
+        }, intervalMs);
+    });
+    if (intervalId !== undefined) {
+        await clearIntervalAsync(intervalId);
+    }
+    return result;
+};

package/build/src/random.d.ts

@@ -0,0 +1,2 @@
+export declare const random: (min: number, max: number) => number;
+//# sourceMappingURL=random.d.ts.map

package/build/src/random.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"random.d.ts","sourceRoot":"","sources":["../../src/random.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,MAAM,QAAS,MAAM,OAAO,MAAM,KAAG,MAEjD,CAAC"}

package/build/src/random.js

@@ -0,0 +1,3 @@
+export const random = (min, max) => {
+    return Math.floor(Math.random() * (max - min + 1) + min);
+};

package/build/src/schema.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod/v4";
+import type { JsonSchema } from "./jsonSchema/index.js";
+export type SchemaMeta = {
+    title?: string;
+    description?: string;
+};
+export type Schema = z.ZodType | JsonSchema;
+export type CheckIsValidSchemaResult = {
+    outcome: "valid";
+} | {
+    outcome: "notValid";
+    errorMessage: string;
+};
+export declare const checkIsValidSchema: (schema: Schema, data: unknown) => CheckIsValidSchemaResult;
+export declare const getSchemaFromPath: (schema: Schema, path: string[]) => Schema | undefined;
+export declare const derivePartialSchema: (schema: Schema, paths: string[][]) => Schema;
+export declare const getSchemaMeta: (schema: Schema) => SchemaMeta;
+export declare const setSchemaMeta: (schema: Schema, meta: SchemaMeta) => Schema;
+export declare const setSchemaMetaFromPath: (schema: Schema, path: string[], meta: SchemaMeta) => Schema;
+export declare const getJsonSchemaFromSchema: (schema: Schema) => JsonSchema;
+export declare const getSchemaType: (schema: Schema) => string | string[];
+export declare const cleanDataFromSchema: (schema: Schema, data: unknown) => unknown;
+export declare const convertSchemaToJsonSchemaInObject: <T>(obj: T) => T;
+//# sourceMappingURL=schema.d.ts.map

package/build/src/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/schema.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAG3B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAcxD,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AACF,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,OAAO,GAAG,UAAU,CAAC;AAE5C,MAAM,MAAM,wBAAwB,GAChC;IACE,OAAO,EAAE,OAAO,CAAC;CAClB,GACD;IACE,OAAO,EAAE,UAAU,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEN,eAAO,MAAM,kBAAkB,WACrB,MAAM,QACR,OAAO,KACZ,wBA8BF,CAAC;AAEF,eAAO,MAAM,iBAAiB,WACpB,MAAM,QACR,MAAM,EAAE,KACb,MAAM,GAAG,SAMX,CAAC;AAEF,eAAO,MAAM,mBAAmB,WACtB,MAAM,SACP,MAAM,EAAE,EAAE,KAChB,MAMF,CAAC;AAEF,eAAO,MAAM,aAAa,WAAY,MAAM,KAAG,UAc9C,CAAC;AAEF,eAAO,MAAM,aAAa,WAAY,MAAM,QAAQ,UAAU,KAAG,MAShE,CAAC;AAEF,eAAO,MAAM,qBAAqB,WACxB,MAAM,QACR,MAAM,EAAE,QACR,UAAU,KACf,MAMF,CAAC;AAEF,eAAO,MAAM,uBAAuB,WAAY,MAAM,KAAG,UA2QxD,CAAC;AAEF,eAAO,MAAM,aAAa,WAAY,MAAM,KAAG,MAAM,GAAG,MAAM,EAgC7D,CAAC;AAEF,eAAO,MAAM,mBAAmB,WAAY,MAAM,QAAQ,OAAO,KAAG,OAQnE,CAAC;AAEF,eAAO,MAAM,iCAAiC,kBAmB7C,CAAC"}

package/build/src/schema.js

@@ -0,0 +1,315 @@
+import { validate as jsonSchemaValidate } from "jsonschema";
+import { z } from "zod/v4";
+import { fromEntries, getEntries } from "./collection.js";
+import { cleanDataFromJsonSchema, derivePartialJsonSchema, getJsonSchemaFromPath, setJsonSchemaMetaFromPath, } from "./jsonSchema/index.js";
+import { derivePartialZod, getZodFromPath, getZodType, setZodMetaFromPath, } from "./zod/index.js";
+export const checkIsValidSchema = (schema, data) => {
+    if (schema instanceof z.ZodType) {
+        const parsed = schema.safeParse(data);
+        if (parsed.success === true) {
+            return {
+                outcome: "valid",
+            };
+        }
+        return {
+            outcome: "notValid",
+            errorMessage: parsed.error.issues
+                .map((issue) => issue.message)
+                .join(", "),
+        };
+    }
+    const result = jsonSchemaValidate(data, schema);
+    if (result.valid === true) {
+        return {
+            outcome: "valid",
+        };
+    }
+    return {
+        outcome: "notValid",
+        errorMessage: result.errors.map((error) => error.message).join(", "),
+    };
+};
+export const getSchemaFromPath = (schema, path) => {
+    if (schema instanceof z.ZodType) {
+        return getZodFromPath(schema, path);
+    }
+    return getJsonSchemaFromPath(schema, path);
+};
+export const derivePartialSchema = (schema, paths) => {
+    if (schema instanceof z.ZodType) {
+        return derivePartialZod(schema, paths);
+    }
+    return derivePartialJsonSchema(schema, paths);
+};
+export const getSchemaMeta = (schema) => {
+    if (schema instanceof z.ZodType) {
+        const meta = schema.meta();
+        return {
+            title: meta !== undefined ? meta.title : undefined,
+            description: meta !== undefined ? meta.description : undefined,
+        };
+    }
+    return {
+        title: schema.title,
+        description: schema.description,
+    };
+};
+export const setSchemaMeta = (schema, meta) => {
+    if (schema instanceof z.ZodType) {
+        return schema.meta(meta);
+    }
+    schema.title = meta.title;
+    schema.description = meta.description;
+    return schema;
+};
+export const setSchemaMetaFromPath = (schema, path, meta) => {
+    if (schema instanceof z.ZodType) {
+        return setZodMetaFromPath(schema, path, meta);
+    }
+    return setJsonSchemaMetaFromPath(schema, path, meta);
+};
+export const getJsonSchemaFromSchema = (schema) => {
+    if (schema instanceof z.ZodType) {
+        return z.toJSONSchema(schema, {
+            unrepresentable: "any",
+            override: (context) => {
+                const definition = context.zodSchema._zod.def;
+                switch (definition.type) {
+                    // Support z.any() as array of all types
+                    case "any": {
+                        context.jsonSchema.type = [
+                            "string",
+                            "number",
+                            "integer",
+                            "boolean",
+                            "object",
+                            "array",
+                            "null",
+                        ];
+                        break;
+                    }
+                    // Support 'date' type as string with date-time format
+                    case "date": {
+                        context.jsonSchema.type = "string";
+                        context.jsonSchema.format = "date-time";
+                        break;
+                    }
+                    // Remove additionalProperties from all schemas in allOf for intersections
+                    case "intersection": {
+                        if (context.jsonSchema.allOf !== undefined) {
+                            for (const schema of context.jsonSchema.allOf) {
+                                if (schema.additionalProperties !== undefined) {
+                                    delete schema.additionalProperties;
+                                }
+                            }
+                        }
+                        break;
+                    }
+                    // Transform discriminated unions into oneOf + allOf with if/else
+                    case "union": {
+                        const { discriminator } = context.zodSchema._zod.def;
+                        if (discriminator === undefined) {
+                            if (context.jsonSchema.anyOf !== undefined &&
+                                context.jsonSchema.anyOf.length > 0) {
+                                const { anyOf } = context.jsonSchema;
+                                const types = anyOf
+                                    .map((option) => {
+                                    if (option.type !== undefined &&
+                                        ["string", "number", "integer", "boolean"].includes(option.type)) {
+                                        return option.type;
+                                    }
+                                    return undefined;
+                                })
+                                    .filter((type) => type !== undefined);
+                                if (types.length !== anyOf.length) {
+                                    break;
+                                }
+                                context.jsonSchema.type =
+                                    types;
+                                delete context.jsonSchema.anyOf;
+                                break;
+                            }
+                            break;
+                        }
+                        const options = context.jsonSchema.anyOf.map((option) => {
+                            if (option.properties === undefined) {
+                                throw new Error(`Missing properties in union option.`);
+                            }
+                            const discriminatorProperty = option.properties[discriminator];
+                            if (discriminatorProperty === undefined ||
+                                typeof discriminatorProperty === "boolean") {
+                                throw new Error(`Missing discriminator property "${discriminator}" in union option.`);
+                            }
+                            const otherProperties = fromEntries(getEntries(option.properties).filter(([key, value]) => {
+                                return key !== discriminator && typeof value !== "boolean";
+                            }));
+                            const requiredOtherProperties = option.required !== undefined
+                                ? option.required.filter((key) => {
+                                    return key !== discriminator;
+                                })
+                                : [];
+                            return {
+                                discriminatorProperty,
+                                otherProperties,
+                                requiredOtherProperties,
+                            };
+                        });
+                        const defaultOption = options[0];
+                        if (defaultOption === undefined) {
+                            throw new Error(`Cannot process union with no options.`);
+                        }
+                        const discriminatorMeta = context.jsonSchema["discriminatorMeta"];
+                        context.jsonSchema.type = "object";
+                        context.jsonSchema.properties = {
+                            [discriminator]: {
+                                type: "string",
+                                title: discriminatorMeta !== undefined
+                                    ? discriminatorMeta.title
+                                    : undefined,
+                                description: discriminatorMeta !== undefined
+                                    ? discriminatorMeta.description
+                                    : undefined,
+                                oneOf: options.map((option) => {
+                                    return {
+                                        const: option.discriminatorProperty.const,
+                                        title: option.discriminatorProperty.title,
+                                        description: option.discriminatorProperty.description,
+                                    };
+                                }),
+                                default: defaultOption.discriminatorProperty.const,
+                            },
+                        };
+                        context.jsonSchema.required = [discriminator];
+                        context.jsonSchema.allOf = options
+                            .map((option) => {
+                            if (Object.keys(option.otherProperties).length === 0) {
+                                return undefined;
+                            }
+                            return {
+                                if: {
+                                    properties: {
+                                        [discriminator]: {
+                                            const: option.discriminatorProperty.const,
+                                        },
+                                    },
+                                },
+                                then: {
+                                    type: "object",
+                                    properties: option.otherProperties,
+                                    required: option.requiredOtherProperties,
+                                },
+                            };
+                        })
+                            .filter((schema) => {
+                            return schema !== undefined;
+                        });
+                        delete context.jsonSchema.anyOf;
+                        delete context.jsonSchema["discriminatorMeta"];
+                        break;
+                    }
+                    case "enum": {
+                        const { entries: enumEntries } = context.zodSchema._zod.def;
+                        const enumMeta = context.jsonSchema["enumMeta"];
+                        if (enumEntries === undefined || enumMeta === undefined) {
+                            break;
+                        }
+                        const enumValues = Object.keys(enumEntries);
+                        context.jsonSchema.oneOf = enumValues.map((enumValue) => {
+                            return {
+                                const: enumValue,
+                                title: enumMeta[enumValue],
+                            };
+                        });
+                        delete context.jsonSchema.enum;
+                        delete context.jsonSchema["enumMeta"];
+                        break;
+                    }
+                    case "nullable": {
+                        if (context.jsonSchema.anyOf !== undefined &&
+                            context.jsonSchema.anyOf.length > 0) {
+                            const { anyOf } = context.jsonSchema;
+                            if (anyOf.length !== 2) {
+                                break;
+                            }
+                            const [typeSchema] = anyOf;
+                            if (typeSchema === undefined || typeSchema.type === undefined) {
+                                break;
+                            }
+                            const types = Array.isArray(typeSchema.type) === true
+                                ? typeSchema.type
+                                : [typeSchema.type];
+                            context.jsonSchema.type = [
+                                ...types,
+                                "null",
+                            ];
+                            delete context.jsonSchema.anyOf;
+                            break;
+                        }
+                        break;
+                    }
+                    case "object": {
+                        if (context.jsonSchema.additionalProperties === false) {
+                            delete context.jsonSchema.additionalProperties;
+                        }
+                        break;
+                    }
+                    default: {
+                        break;
+                    }
+                }
+            },
+        });
+    }
+    return schema;
+};
+export const getSchemaType = (schema) => {
+    if (schema instanceof z.ZodType) {
+        const type = getZodType(schema);
+        if (type === "any") {
+            return [
+                "string",
+                "number",
+                "integer",
+                "boolean",
+                "object",
+                "array",
+                "null",
+            ];
+        }
+        return type;
+    }
+    if (schema.type === undefined) {
+        return [
+            "string",
+            "number",
+            "integer",
+            "boolean",
+            "object",
+            "array",
+            "null",
+        ];
+    }
+    return schema.type;
+};
+export const cleanDataFromSchema = (schema, data) => {
+    if (schema instanceof z.ZodType) {
+        const parsed = schema.safeParse(data);
+        return parsed.success === true ? parsed.data : undefined;
+    }
+    return cleanDataFromJsonSchema(schema, data);
+};
+export const convertSchemaToJsonSchemaInObject = (obj) => {
+    if (obj instanceof z.ZodType) {
+        return getJsonSchemaFromSchema(obj);
+    }
+    if (Array.isArray(obj) === true) {
+        return obj.map((item) => convertSchemaToJsonSchemaInObject(item));
+    }
+    if (obj !== null && typeof obj === "object") {
+        return fromEntries(getEntries(obj).map(([key, value]) => [
+            key,
+            convertSchemaToJsonSchemaInObject(value),
+        ]));
+    }
+    return obj;
+};

package/build/src/searchInTree.d.ts

@@ -0,0 +1,46 @@
+type SearchInTreeAlgorithm = "DFS" | "BFS";
+/**
+ * Options for the searchInTree function.
+ * @template T - Type of the tree node.
+ */
+export type SearchInTreeOptions<T> = {
+    /** The key or keys to search within each node. */
+    searchKeyOrKeys: keyof T | (keyof T)[];
+    /** The key representing the children of a node (default is 'children'). */
+    childrenKey?: keyof T | "children";
+    /** The traversal algorithm, either "DFS" (default) or "BFS". */
+    algorithm?: SearchInTreeAlgorithm;
+    /** Whether the search should be case-sensitive (default: false). */
+    caseSensitive?: boolean;
+};
+/**
+ * The searchInTree function return an object with a generator and an additional unwrap method to return results as an array.
+ * @template T - Type of the tree node.
+ */
+type SearchInTreeReturn<T> = {
+    /** Allows iteration over the results like a generator. */
+    [Symbol.iterator]: () => Generator<T>;
+    /** Converts the results to an array. */
+    unwrap: () => T[];
+};
+/**
+ * Generator function to search for nodes in a tree structure.
+ * Supports both Depth-First Search (DFS) and Breadth-First Search (BFS).
+ *
+ * @template T - Type of the tree node.
+ * @param {T[]} data - The tree data to traverse.
+ * @param {string} searchTerm - The term to search for.
+ * @param {SearchInTreeOptions<T>} options - Additional options for the search.
+ * @returns {SearchInTreeReturn<T>} - An iterable object to traverse the search results.
+ *
+ * @example
+ * const results = searchInTree(dataset, "example", {
+ *   searchKeyOrKeys: "name",
+ *   childrenKey: "children",
+ *   algorithm: "DFS",
+ *   caseSensitive: false,
+ * }).unwrap();
+ */
+export declare function searchInTree<T extends Record<string, unknown>>(data: T[], searchTerm: string, { searchKeyOrKeys, childrenKey, algorithm, caseSensitive, }: SearchInTreeOptions<T>): SearchInTreeReturn<T>;
+export {};
+//# sourceMappingURL=searchInTree.d.ts.map

package/build/src/searchInTree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"searchInTree.d.ts","sourceRoot":"","sources":["../../src/searchInTree.ts"],"names":[],"mappings":"AAAA,KAAK,qBAAqB,GAAG,KAAK,GAAG,KAAK,CAAC;AAE3C;;;GAGG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI;IACnC,kDAAkD;IAClD,eAAe,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;IACvC,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC,GAAG,UAAU,CAAC;IACnC,gEAAgE;IAChE,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,oEAAoE;IACpE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF;;;GAGG;AACH,KAAK,kBAAkB,CAAC,CAAC,IAAI;IAC3B,0DAA0D;IAC1D,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,MAAM,SAAS,CAAC,CAAC,CAAC,CAAC;IACtC,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;CACnB,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AAEH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5D,IAAI,EAAE,CAAC,EAAE,EACT,UAAU,EAAE,MAAM,EAClB,EACE,eAAe,EACf,WAAwB,EACxB,SAAiB,EACjB,aAAqB,GACtB,EAAE,mBAAmB,CAAC,CAAC,CAAC,GACxB,kBAAkB,CAAC,CAAC,CAAC,CAmDvB"}

package/build/src/searchInTree.js

@@ -0,0 +1,67 @@
+/**
+ * Generator function to search for nodes in a tree structure.
+ * Supports both Depth-First Search (DFS) and Breadth-First Search (BFS).
+ *
+ * @template T - Type of the tree node.
+ * @param {T[]} data - The tree data to traverse.
+ * @param {string} searchTerm - The term to search for.
+ * @param {SearchInTreeOptions<T>} options - Additional options for the search.
+ * @returns {SearchInTreeReturn<T>} - An iterable object to traverse the search results.
+ *
+ * @example
+ * const results = searchInTree(dataset, "example", {
+ *   searchKeyOrKeys: "name",
+ *   childrenKey: "children",
+ *   algorithm: "DFS",
+ *   caseSensitive: false,
+ * }).unwrap();
+ */
+export function searchInTree(data, searchTerm, { searchKeyOrKeys, childrenKey = "children", algorithm = "DFS", caseSensitive = false, }) {
+    const keys = Array.isArray(searchKeyOrKeys)
+        ? searchKeyOrKeys
+        : [searchKeyOrKeys];
+    const queue = [...data];
+    function* generator() {
+        while (queue.length > 0) {
+            const node = algorithm === "DFS" ? queue.pop() : queue.shift();
+            if (node === undefined) {
+                continue;
+            }
+            const matches = isNodeMatchingSearchTerm(node, searchTerm, keys, caseSensitive);
+            const children = Array.isArray(node[childrenKey])
+                ? [...node[childrenKey]]
+                : [];
+            const filteredChildren = [];
+            for (const child of children) {
+                if (isNodeMatchingSearchTerm(child, searchTerm, keys, caseSensitive) ===
+                    true) {
+                    filteredChildren.push(child);
+                }
+                else {
+                    queue.push(child);
+                }
+            }
+            if (matches === true || filteredChildren.length > 0) {
+                yield {
+                    ...node,
+                    [childrenKey]: filteredChildren.length > 0 ? filteredChildren : node[childrenKey],
+                };
+            }
+        }
+    }
+    return {
+        [Symbol.iterator]: () => generator(),
+        unwrap: () => Array.from(generator()),
+    };
+}
+function isNodeMatchingSearchTerm(node, searchTerm, keys, caseSensitive) {
+    return keys.some((key) => {
+        const value = node[key];
+        if (typeof value !== "string") {
+            return false;
+        }
+        return caseSensitive
+            ? value.includes(searchTerm)
+            : value.toLowerCase().includes(searchTerm.toLowerCase());
+    });
+}

package/build/src/storage.d.ts

@@ -0,0 +1,13 @@
+export declare const matchIsLocalStorageSupported: () => boolean;
+export declare const matchIsIndexedDBSupported: () => Promise<boolean>;
+export type Storage = "localStorage" | "indexedDB";
+export declare const getItemFromStorage: <T>(key: string, options?: {
+    storage?: Storage;
+}) => Promise<T | undefined>;
+export declare const setItemInStorage: <T>(key: string, value: T, options?: {
+    storage?: Storage;
+}) => Promise<T>;
+export declare const removeItemFromStorage: (key: string, options?: {
+    storage?: Storage;
+}) => Promise<void>;
+//# sourceMappingURL=storage.d.ts.map

package/build/src/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/storage.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,4BAA4B,QAAO,OAmB/C,CAAC;AAGF,eAAO,MAAM,yBAAyB,QAAa,QAAQ,OAAO,CA2GjE,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG,cAAc,GAAG,WAAW,CAAC;AAEnD,eAAO,MAAM,kBAAkB,WACxB,MAAM,YACF;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,2BAuC/B,CAAC;AAEF,eAAO,MAAM,gBAAgB,WACtB,MAAM,sBAEF;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,eAiC/B,CAAC;AAEF,eAAO,MAAM,qBAAqB,QAC3B,MAAM,YACF;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,KAC7B,QAAQ,IAAI,CA2Bd,CAAC"}