@proseql/core 0.1.0

package/dist/utils/id-generator.js

@@ -0,0 +1,247 @@
+/**
+ * ID generation utility with uniqueness guarantees
+ * Provides various ID generation strategies for database entities
+ */
+// ============================================================================
+// ID Generation Strategies
+// ============================================================================
+/**
+ * Counter for sequential IDs within a process
+ * Reset on process restart
+ */
+let sequentialCounter = 0;
+/**
+ * Generate a timestamp-based ID with microsecond precision
+ * Format: timestamp-random-counter
+ * Example: "1704067200000-a3f2-0001"
+ */
+export function generateTimestampId() {
+    const timestamp = Date.now();
+    const random = Math.random().toString(36).substring(2, 6);
+    const counter = (++sequentialCounter).toString().padStart(4, "0");
+    return `${timestamp}-${random}-${counter}`;
+}
+/**
+ * Generate a nano ID - URL-safe, short, unique identifier
+ * Uses a larger alphabet for better uniqueness in shorter strings
+ */
+export function generateNanoId(length = 21) {
+    const alphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz-_";
+    let id = "";
+    // Use crypto for better randomness if available
+    if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+        const bytes = new Uint8Array(length);
+        crypto.getRandomValues(bytes);
+        for (let i = 0; i < length; i++) {
+            id += alphabet[bytes[i] % alphabet.length];
+        }
+    }
+    else {
+        // Fallback to Math.random
+        for (let i = 0; i < length; i++) {
+            id += alphabet[Math.floor(Math.random() * alphabet.length)];
+        }
+    }
+    return id;
+}
+/**
+ * Generate a UUID v4 compliant identifier
+ * Standard format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+ */
+export function generateUUID() {
+    if (typeof crypto !== "undefined" && crypto.randomUUID) {
+        return crypto.randomUUID();
+    }
+    // Fallback implementation
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === "x" ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+/**
+ * Generate a prefixed ID for better organization
+ * Format: prefix_id
+ * Example: "user_1704067200000-a3f2-0001"
+ */
+export function generatePrefixedId(prefix) {
+    const id = generateTimestampId();
+    return `${prefix}_${id}`;
+}
+/**
+ * Generate a ULID (Universally Unique Lexicographically Sortable Identifier)
+ * Sortable by creation time, case-insensitive
+ */
+export function generateULID() {
+    const timestamp = Date.now();
+    const timestampChars = encodeTime(timestamp, 10);
+    const randomChars = encodeRandom(16);
+    return timestampChars + randomChars;
+}
+// ULID helper functions
+const ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"; // Crockford's Base32
+function encodeTime(timestamp, length) {
+    let str = "";
+    for (let i = length - 1; i >= 0; i--) {
+        const mod = timestamp % ENCODING.length;
+        str = ENCODING[mod] + str;
+        timestamp = Math.floor(timestamp / ENCODING.length);
+    }
+    return str;
+}
+function encodeRandom(length) {
+    let str = "";
+    for (let i = 0; i < length; i++) {
+        str += ENCODING[Math.floor(Math.random() * ENCODING.length)];
+    }
+    return str;
+}
+/**
+ * Generate a sortable ID that includes type information
+ * Format: type:timestamp:random
+ * Example: "user:1704067200000:a3f2"
+ */
+export function generateTypedId(type) {
+    const timestamp = Date.now();
+    const random = generateNanoId(4);
+    return `${type}:${timestamp}:${random}`;
+}
+// ============================================================================
+// ID Validation
+// ============================================================================
+/**
+ * Check if a string is a valid ID format
+ */
+export function isValidId(id) {
+    return typeof id === "string" && id.length > 0 && !id.includes("\0");
+}
+/**
+ * Check if ID matches expected format
+ */
+export function isValidIdFormat(id, format) {
+    switch (format) {
+        case "uuid":
+            return /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(id);
+        case "ulid":
+            return /^[0-9A-Z]{26}$/i.test(id);
+        case "timestamp":
+            return /^\d{13}-[a-z0-9]{4}-\d{4}$/.test(id);
+        case "nano":
+            return /^[0-9A-Za-z_-]+$/.test(id);
+        default:
+            return false;
+    }
+}
+/**
+ * Default ID generator configuration
+ */
+export const defaultIdConfig = {
+    strategy: "nano",
+    length: 21,
+};
+/**
+ * Create an ID generator with specific configuration
+ */
+export function createIdGenerator(config = defaultIdConfig) {
+    switch (config.strategy) {
+        case "timestamp":
+            return generateTimestampId;
+        case "nano":
+            return () => generateNanoId(config.length);
+        case "uuid":
+            return generateUUID;
+        case "ulid":
+            return generateULID;
+        case "prefixed": {
+            if (!config.prefix) {
+                throw new Error("Prefix required for prefixed ID strategy");
+            }
+            const prefix = config.prefix;
+            return () => generatePrefixedId(prefix);
+        }
+        case "typed": {
+            if (!config.type) {
+                throw new Error("Type required for typed ID strategy");
+            }
+            const type = config.type;
+            return () => generateTypedId(type);
+        }
+        default:
+            throw new Error(`Unknown ID strategy: ${config.strategy}`);
+    }
+}
+// ============================================================================
+// Default Export
+// ============================================================================
+/**
+ * Default ID generator using nano ID strategy
+ */
+export const generateId = createIdGenerator(defaultIdConfig);
+/**
+ * Collection-specific ID generators
+ * Allows different ID strategies per collection
+ */
+export class CollectionIdGenerators {
+    generators = new Map();
+    defaultGenerator;
+    constructor(defaultConfig = defaultIdConfig) {
+        this.defaultGenerator = createIdGenerator(defaultConfig);
+    }
+    /**
+     * Register a custom ID generator for a collection
+     */
+    register(collection, config) {
+        this.generators.set(collection, createIdGenerator(config));
+    }
+    /**
+     * Get ID generator for a collection
+     */
+    getGenerator(collection) {
+        return this.generators.get(collection) || this.defaultGenerator;
+    }
+    /**
+     * Generate ID for a collection
+     */
+    generateFor(collection) {
+        return this.getGenerator(collection)();
+    }
+}
+// ============================================================================
+// ID Utilities
+// ============================================================================
+/**
+ * Extract timestamp from timestamp-based IDs
+ */
+export function extractTimestamp(id) {
+    // Handle timestamp format
+    const timestampMatch = id.match(/^(\d{13})-/);
+    if (timestampMatch) {
+        return parseInt(timestampMatch[1], 10);
+    }
+    // Handle typed format
+    const typedMatch = id.match(/:(\d{13}):/);
+    if (typedMatch) {
+        return parseInt(typedMatch[1], 10);
+    }
+    return null;
+}
+/**
+ * Extract type from typed IDs
+ */
+export function extractType(id) {
+    const match = id.match(/^([^:]+):/);
+    return match ? match[1] : null;
+}
+/**
+ * Compare IDs for sorting (works with timestamp-based IDs)
+ */
+export function compareIds(a, b) {
+    const timestampA = extractTimestamp(a);
+    const timestampB = extractTimestamp(b);
+    if (timestampA !== null && timestampB !== null) {
+        return timestampA - timestampB;
+    }
+    // Fallback to string comparison
+    return a.localeCompare(b);
+}
+//# sourceMappingURL=id-generator.js.map

package/dist/utils/id-generator.js.map

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

package/dist/utils/nested-path.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Utilities for resolving and mutating nested object paths using dot notation.
+ */
+/**
+ * Check if a string is a dot-notation path (contains at least one ".").
+ *
+ * @param key - The string to check
+ * @returns true if the key contains a dot
+ */
+export declare function isDotPath(key: string): boolean;
+/**
+ * Get a nested value from an object using dot notation.
+ * Handles single-segment paths (no ".") as direct property access with no overhead.
+ *
+ * @param obj - The object to get the value from
+ * @param path - The dot-separated path to the value (e.g., "metadata.views")
+ * @returns The value at the path, or undefined if not found
+ *
+ * @example
+ * getNestedValue({ a: { b: 1 } }, "a.b") // returns 1
+ * getNestedValue({ a: { b: 1 } }, "a") // returns { b: 1 }
+ * getNestedValue({ a: { b: 1 } }, "a.c") // returns undefined
+ * getNestedValue({ name: "foo" }, "name") // returns "foo" (single-segment, direct access)
+ */
+export declare function getNestedValue(obj: Record<string, unknown>, path: string): unknown;
+/**
+ * Recursively collect all paths in an object that have string values.
+ * Used for auto-discovering searchable fields when no explicit fields are specified.
+ *
+ * @param obj - The object to traverse
+ * @param prefix - The current path prefix (used during recursion)
+ * @returns An array of dot-notation paths pointing to string values
+ *
+ * @example
+ * collectStringPaths({ name: "foo", metadata: { description: "bar", count: 5 } })
+ * // returns ["name", "metadata.description"]
+ */
+export declare function collectStringPaths(obj: Record<string, unknown>, prefix?: string): ReadonlyArray<string>;
+/**
+ * Set a nested value on an object using dot notation, returning a new object (immutable).
+ * Creates intermediate objects along the path if they don't exist.
+ * Handles single-segment paths (no ".") as direct property set with no overhead.
+ *
+ * @param obj - The source object
+ * @param path - The dot-separated path where to set the value (e.g., "metadata.views")
+ * @param value - The value to set
+ * @returns A new object with the value set at the path
+ *
+ * @example
+ * setNestedValue({ a: { b: 1 } }, "a.b", 2) // returns { a: { b: 2 } }
+ * setNestedValue({ a: { b: 1 } }, "a.c", 3) // returns { a: { b: 1, c: 3 } }
+ * setNestedValue({}, "a.b.c", 1) // returns { a: { b: { c: 1 } } }
+ * setNestedValue({ name: "foo" }, "name", "bar") // returns { name: "bar" } (single-segment)
+ */
+export declare function setNestedValue(obj: Record<string, unknown>, path: string, value: unknown): Record<string, unknown>;
+//# sourceMappingURL=nested-path.d.ts.map

package/dist/utils/nested-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nested-path.d.ts","sourceRoot":"","sources":["../../src/utils/nested-path.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE9C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC7B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,IAAI,EAAE,MAAM,GACV,OAAO,CAuBT;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,MAAM,SAAK,GACT,aAAa,CAAC,MAAM,CAAC,CAmBvB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAC7B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,GACZ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA+BzB"}

package/dist/utils/nested-path.js

@@ -0,0 +1,119 @@
+/**
+ * Utilities for resolving and mutating nested object paths using dot notation.
+ */
+/**
+ * Check if a string is a dot-notation path (contains at least one ".").
+ *
+ * @param key - The string to check
+ * @returns true if the key contains a dot
+ */
+export function isDotPath(key) {
+    return key.includes(".");
+}
+/**
+ * Get a nested value from an object using dot notation.
+ * Handles single-segment paths (no ".") as direct property access with no overhead.
+ *
+ * @param obj - The object to get the value from
+ * @param path - The dot-separated path to the value (e.g., "metadata.views")
+ * @returns The value at the path, or undefined if not found
+ *
+ * @example
+ * getNestedValue({ a: { b: 1 } }, "a.b") // returns 1
+ * getNestedValue({ a: { b: 1 } }, "a") // returns { b: 1 }
+ * getNestedValue({ a: { b: 1 } }, "a.c") // returns undefined
+ * getNestedValue({ name: "foo" }, "name") // returns "foo" (single-segment, direct access)
+ */
+export function getNestedValue(obj, path) {
+    // Fast path: single-segment path (no dot) - direct property access
+    if (!isDotPath(path)) {
+        return obj[path];
+    }
+    // Multi-segment path: traverse the object
+    const parts = path.split(".");
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined) {
+            return undefined;
+        }
+        if (typeof current === "object") {
+            current = current[part];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return current;
+}
+/**
+ * Recursively collect all paths in an object that have string values.
+ * Used for auto-discovering searchable fields when no explicit fields are specified.
+ *
+ * @param obj - The object to traverse
+ * @param prefix - The current path prefix (used during recursion)
+ * @returns An array of dot-notation paths pointing to string values
+ *
+ * @example
+ * collectStringPaths({ name: "foo", metadata: { description: "bar", count: 5 } })
+ * // returns ["name", "metadata.description"]
+ */
+export function collectStringPaths(obj, prefix = "") {
+    const paths = [];
+    for (const [key, value] of Object.entries(obj)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (typeof value === "string") {
+            paths.push(path);
+        }
+        else if (value !== null &&
+            typeof value === "object" &&
+            !Array.isArray(value)) {
+            // Recurse into nested objects (but not arrays)
+            paths.push(...collectStringPaths(value, path));
+        }
+    }
+    return paths;
+}
+/**
+ * Set a nested value on an object using dot notation, returning a new object (immutable).
+ * Creates intermediate objects along the path if they don't exist.
+ * Handles single-segment paths (no ".") as direct property set with no overhead.
+ *
+ * @param obj - The source object
+ * @param path - The dot-separated path where to set the value (e.g., "metadata.views")
+ * @param value - The value to set
+ * @returns A new object with the value set at the path
+ *
+ * @example
+ * setNestedValue({ a: { b: 1 } }, "a.b", 2) // returns { a: { b: 2 } }
+ * setNestedValue({ a: { b: 1 } }, "a.c", 3) // returns { a: { b: 1, c: 3 } }
+ * setNestedValue({}, "a.b.c", 1) // returns { a: { b: { c: 1 } } }
+ * setNestedValue({ name: "foo" }, "name", "bar") // returns { name: "bar" } (single-segment)
+ */
+export function setNestedValue(obj, path, value) {
+    // Fast path: single-segment path (no dot) - direct property set
+    if (!isDotPath(path)) {
+        return { ...obj, [path]: value };
+    }
+    // Multi-segment path: build the nested structure
+    const parts = path.split(".");
+    const result = { ...obj };
+    let current = result;
+    // Navigate/create to the parent of the leaf
+    for (let i = 0; i < parts.length - 1; i++) {
+        const part = parts[i];
+        const existing = current[part];
+        // Copy or create the intermediate object
+        if (existing !== null && typeof existing === "object") {
+            current[part] = { ...existing };
+        }
+        else {
+            current[part] = {};
+        }
+        current = current[part];
+    }
+    // Set the leaf value
+    const leafKey = parts[parts.length - 1];
+    current[leafKey] = value;
+    return result;
+}
+//# sourceMappingURL=nested-path.js.map

package/dist/utils/nested-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nested-path.js","sourceRoot":"","sources":["../../src/utils/nested-path.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW;IACpC,OAAO,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAC7B,GAA4B,EAC5B,IAAY;IAEZ,mEAAmE;IACnE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;IAED,0CAA0C;IAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,OAAO,GAAY,GAAG,CAAC;IAE3B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC1B,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC/C,OAAO,SAAS,CAAC;QAClB,CAAC;QAED,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YACjC,OAAO,GAAI,OAAmC,CAAC,IAAI,CAAC,CAAC;QACtD,CAAC;aAAM,CAAC;YACP,OAAO,SAAS,CAAC;QAClB,CAAC;IACF,CAAC;IAED,OAAO,OAAO,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CACjC,GAA4B,EAC5B,MAAM,GAAG,EAAE;IAEX,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;QAE/C,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC/B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClB,CAAC;aAAM,IACN,KAAK,KAAK,IAAI;YACd,OAAO,KAAK,KAAK,QAAQ;YACzB,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EACpB,CAAC;YACF,+CAA+C;YAC/C,KAAK,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,KAAgC,EAAE,IAAI,CAAC,CAAC,CAAC;QAC3E,CAAC;IACF,CAAC;IAED,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,cAAc,CAC7B,GAA4B,EAC5B,IAAY,EACZ,KAAc;IAEd,gEAAgE;IAChE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC;IAClC,CAAC;IAED,iDAAiD;IACjD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,MAAM,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC;IAC1B,IAAI,OAAO,GAA4B,MAAM,CAAC;IAE9C,4CAA4C;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3C,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAE/B,yCAAyC;QACzC,IAAI,QAAQ,KAAK,IAAI,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACvD,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,GAAI,QAAoC,EAAE,CAAC;QAC9D,CAAC;aAAM,CAAC;YACP,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QACpB,CAAC;QAED,OAAO,GAAG,OAAO,CAAC,IAAI,CAA4B,CAAC;IACpD,CAAC;IAED,qBAAqB;IACrB,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACxC,OAAO,CAAC,OAAO,CAAC,GAAG,KAAK,CAAC;IAEzB,OAAO,MAAM,CAAC;AACf,CAAC"}

package/dist/utils/path.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Path utilities for file operations.
+ */
+/**
+ * Extract the file extension from a file path without the leading dot.
+ *
+ * @param filePath - The file path to extract extension from
+ * @returns The file extension without the dot, or empty string if no extension
+ *
+ * @example
+ * getFileExtension('/path/to/file.json') // returns 'json'
+ * getFileExtension('/path/to/file.data.yaml') // returns 'yaml'
+ * getFileExtension('/path/to/file') // returns ''
+ */
+export declare function getFileExtension(filePath: string): string;
+//# sourceMappingURL=path.d.ts.map

package/dist/utils/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../../src/utils/path.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAazD"}

package/dist/utils/path.js

@@ -0,0 +1,24 @@
+/**
+ * Path utilities for file operations.
+ */
+/**
+ * Extract the file extension from a file path without the leading dot.
+ *
+ * @param filePath - The file path to extract extension from
+ * @returns The file extension without the dot, or empty string if no extension
+ *
+ * @example
+ * getFileExtension('/path/to/file.json') // returns 'json'
+ * getFileExtension('/path/to/file.data.yaml') // returns 'yaml'
+ * getFileExtension('/path/to/file') // returns ''
+ */
+export function getFileExtension(filePath) {
+    const lastDotIndex = filePath.lastIndexOf(".");
+    const lastSlashIndex = Math.max(filePath.lastIndexOf("/"), filePath.lastIndexOf("\\"));
+    // If there's no dot, or the dot is before the last slash/backslash (part of directory name)
+    if (lastDotIndex === -1 || lastDotIndex <= lastSlashIndex) {
+        return "";
+    }
+    return filePath.slice(lastDotIndex + 1).toLowerCase();
+}
+//# sourceMappingURL=path.js.map

package/dist/utils/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../../src/utils/path.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAChD,MAAM,YAAY,GAAG,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC/C,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAC9B,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,EACzB,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,CAC1B,CAAC;IAEF,4FAA4F;IAC5F,IAAI,YAAY,KAAK,CAAC,CAAC,IAAI,YAAY,IAAI,cAAc,EAAE,CAAC;QAC3D,OAAO,EAAE,CAAC;IACX,CAAC;IAED,OAAO,QAAQ,CAAC,KAAK,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;AACvD,CAAC"}

package/dist/validators/foreign-key.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Foreign key validation system.
+ *
+ * Effect-based validators use Ref<ReadonlyMap> for O(1) lookups.
+ */
+import { Effect, Ref } from "effect";
+import { ForeignKeyError } from "../errors/crud-errors.js";
+import type { ForeignKeyValidation } from "../types/crud-types.js";
+import type { RelationshipDef } from "../types/types.js";
+type HasId = {
+    readonly id: string;
+};
+type RelationshipConfig = {
+    readonly type: "ref" | "inverse";
+    readonly target?: string;
+    readonly foreignKey?: string;
+};
+/**
+ * Extract foreign key configurations from relationships
+ */
+export declare function extractForeignKeyConfigs(relationships: Record<string, RelationshipDef<unknown, "ref" | "inverse", string>>): ForeignKeyValidation[];
+/**
+ * Validate foreign keys for an entity using Ref-based state.
+ * Returns Effect that fails with ForeignKeyError if a violation is found.
+ *
+ * Uses ReadonlyMap for O(1) lookups instead of legacy array scanning.
+ */
+export declare const validateForeignKeysEffect: <T extends HasId>(entity: T, collectionName: string, relationships: Record<string, RelationshipConfig>, stateRefs: Record<string, Ref.Ref<ReadonlyMap<string, HasId>>>) => Effect.Effect<void, ForeignKeyError>;
+/**
+ * Check if deleting an entity would violate foreign key constraints.
+ * Scans all collections for "ref" relationships targeting this collection
+ * whose foreign key field references the entity being deleted.
+ *
+ * Returns Effect that fails with ForeignKeyError if violations exist.
+ */
+export declare const checkDeleteConstraintsEffect: (entityId: string, collectionName: string, allRelationships: Record<string, Record<string, RelationshipConfig>>, stateRefs: Record<string, Ref.Ref<ReadonlyMap<string, HasId>>>) => Effect.Effect<void, ForeignKeyError>;
+/**
+ * Check referential integrity for an entire database using Ref-based state.
+ * Returns Effect with a list of violations.
+ */
+export declare const checkReferentialIntegrityEffect: (allRelationships: Record<string, Record<string, RelationshipConfig>>, stateRefs: Record<string, Ref.Ref<ReadonlyMap<string, HasId>>>) => Effect.Effect<ReadonlyArray<{
+    readonly collection: string;
+    readonly entityId: string;
+    readonly field: string;
+    readonly invalidReference: unknown;
+    readonly targetCollection: string;
+}>>;
+export {};
+//# sourceMappingURL=foreign-key.d.ts.map

package/dist/validators/foreign-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foreign-key.d.ts","sourceRoot":"","sources":["../../src/validators/foreign-key.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAMzD,KAAK,KAAK,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAErC,KAAK,kBAAkB,GAAG;IACzB,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAMF;;GAEG;AACH,wBAAgB,wBAAwB,CACvC,aAAa,EAAE,MAAM,CACpB,MAAM,EACN,eAAe,CAAC,OAAO,EAAE,KAAK,GAAG,SAAS,EAAE,MAAM,CAAC,CACnD,GACC,oBAAoB,EAAE,CAoBxB;AAMD;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GAAI,CAAC,SAAS,KAAK,EACxD,QAAQ,CAAC,EACT,gBAAgB,MAAM,EACtB,eAAe,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,EACjD,WAAW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,KAC5D,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAoDrC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,GACxC,UAAU,MAAM,EAChB,gBAAgB,MAAM,EACtB,kBAAkB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,EACpE,WAAW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,KAC5D,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAkCnC,CAAC;AAEJ;;;GAGG;AACH,eAAO,MAAM,+BAA+B,GAC3C,kBAAkB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,EACpE,WAAW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,KAC5D,MAAM,CAAC,MAAM,CACf,aAAa,CAAC;IACb,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CAClC,CAAC,CAyDA,CAAC"}