@warlock.js/cascade 4.0.162 → 4.0.164

package/cjs/events/model-events.js

@@ -0,0 +1,259 @@
+'use strict';/**
+ * Light-weight async event emitter used to power model lifecycle hooks.
+ *
+ * The implementation intentionally avoids any external dependency so we can
+ * re-use it in drivers, writers, and other core services without pulling in
+ * heavier event libraries.
+ */
+class ModelEvents {
+    listeners = new Map();
+    /**
+     * Register a listener for the given event.
+     * Returns an unsubscribe function for convenience.
+     */
+    on(event, listener) {
+        const listeners = this.ensureListenerSet(event);
+        listeners.add(listener);
+        return () => this.off(event, listener);
+    }
+    /**
+     * Register a listener that automatically unsubscribes after the first call.
+     */
+    once(event, listener) {
+        const wrapper = async (model, context) => {
+            try {
+                await listener(model, context);
+            }
+            finally {
+                this.off(event, wrapper);
+            }
+        };
+        return this.on(event, wrapper);
+    }
+    /**
+     * Deregister a listener for the given event.
+     */
+    off(event, listener) {
+        const listeners = this.listeners.get(event);
+        if (!listeners) {
+            return;
+        }
+        listeners.delete(listener);
+        if (listeners.size === 0) {
+            this.listeners.delete(event);
+        }
+    }
+    /**
+     * Emit an event to all registered listeners.
+     */
+    async emit(event, model, context) {
+        const listeners = this.listeners.get(event);
+        if (!listeners || listeners.size === 0) {
+            return;
+        }
+        for (const listener of Array.from(listeners)) {
+            await listener(model, context);
+        }
+    }
+    /**
+     * Emit events for fetching
+     */
+    async emitFetching(query, context) {
+        await this.emit("fetching", query, context);
+    }
+    /**
+     * Remove all registered listeners.
+     */
+    clear() {
+        this.listeners.clear();
+    }
+    /**
+     * Registers a listener for the "saving" event.
+     *
+     * Fired before a model is persisted (both insert and update), and before validation.
+     * Use this hook for data enrichment and preparation (e.g., setting createdBy, updatedBy).
+     *
+     * @param listener - The callback to invoke
+     * @returns An unsubscribe function
+     */
+    onSaving(listener) {
+        return this.on("saving", listener);
+    }
+    /**
+     * Registers a listener for the "saved" event.
+     *
+     * Fired after a model has been successfully persisted.
+     *
+     * @param listener - The callback to invoke
+     * @returns An unsubscribe function
+     */
+    onSaved(listener) {
+        return this.on("saved", listener);
+    }
+    /**
+     * Registers a listener for the "creating" event.
+     *
+     * Fired before a new model is inserted into the database.
+     *
+     * @param listener - The callback to invoke
+     * @returns An unsubscribe function
+     */
+    onCreating(listener) {
+        return this.on("creating", listener);
+    }
+    /**
+     * Registers a listener for the "created" event.
+     *
+     * Fired after a new model has been successfully inserted.
+     *
+     * @param listener - The callback to invoke
+     * @returns An unsubscribe function
+     */
+    onCreated(listener) {
+        return this.on("created", listener);
+    }
+    /**
+     * Registers a listener for the "updating" event.
+     *
+     * Fired before an existing model is updated in the database.
+     *
+     * @param listener - The callback to invoke
+     * @returns An unsubscribe function
+     */
+    onUpdating(listener) {
+        return this.on("updating", listener);
+    }
+    /**
+     * Registers a listener for the "updated" event.
+     *
+     * Fired after an existing model has been successfully updated.
+     *
+     * @param listener - The callback to invoke
+     * @returns An unsubscribe function
+     */
+    onUpdated(listener) {
+        return this.on("updated", listener);
+    }
+    /**
+     * Registers a listener for the "deleting" event.
+     *
+     * Fired before a model is deleted from the database.
+     *
+     * @param listener - The callback to invoke
+     * @returns An unsubscribe function
+     */
+    onDeleting(listener) {
+        return this.on("deleting", listener);
+    }
+    /**
+     * Registers a listener for the "deleted" event.
+     *
+     * Fired after a model has been successfully deleted.
+     *
+     * @param listener - The callback to invoke
+     * @returns An unsubscribe function
+     */
+    onDeleted(listener) {
+        return this.on("deleted", listener);
+    }
+    /**
+     * Registers a listener for the "validating" event.
+     *
+     * Fired before model validation is performed.
+     *
+     * @param listener - The callback to invoke
+     * @returns An unsubscribe function
+     */
+    onValidating(listener) {
+        return this.on("validating", listener);
+    }
+    /**
+     * Registers a listener for the "validated" event.
+     *
+     * Fired after model validation has completed.
+     *
+     * @param listener - The callback to invoke
+     * @returns An unsubscribe function
+     */
+    onValidated(listener) {
+        return this.on("validated", listener);
+    }
+    /**
+     * Registers a listener for the "fetching" event.
+     *
+     * Fired before a query is executed to fetch models.
+     * Receives the query builder instance, allowing modification before execution.
+     *
+     * @param listener - The callback to invoke
+     * @returns An unsubscribe function
+     */
+    onFetching(listener) {
+        return this.on("fetching", listener);
+    }
+    /**
+     * Registers a listener for the "hydrating" event.
+     *
+     * Fired after raw records are fetched but before they are hydrated into model instances.
+     * Allows modification of raw data before hydration.
+     *
+     * @param listener - The callback to invoke
+     * @returns An unsubscribe function
+     */
+    onHydrating(listener) {
+        return this.on("hydrating", listener);
+    }
+    /**
+     * Registers a listener for the "fetched" event.
+     *
+     * Fired after models have been fetched and hydrated.
+     * Receives hydrated model instances and query context.
+     *
+     * @param listener - The callback to invoke
+     * @returns An unsubscribe function
+     */
+    onFetched(listener) {
+        return this.on("fetched", listener);
+    }
+    /**
+     * Registers a listener for the "restoring" event.
+     *
+     * Fired before a soft-deleted model is restored.
+     *
+     * @param listener - The callback to invoke
+     * @returns An unsubscribe function
+     */
+    onRestoring(listener) {
+        return this.on("restoring", listener);
+    }
+    /**
+     * Registers a listener for the "restored" event.
+     *
+     * Fired after a soft-deleted model has been successfully restored.
+     *
+     * @param listener - The callback to invoke
+     * @returns An unsubscribe function
+     */
+    onRestored(listener) {
+        return this.on("restored", listener);
+    }
+    /**
+     * Ensures a listener set exists for the given event.
+     *
+     * @param event - The event name
+     * @returns The listener set for the event
+     * @private
+     */
+    ensureListenerSet(event) {
+        let listeners = this.listeners.get(event);
+        if (!listeners) {
+            listeners = new Set();
+            this.listeners.set(event, listeners);
+        }
+        return listeners;
+    }
+}
+/**
+ * Global event emitter invoked for every model instance, regardless of type.
+ * Useful for cross-cutting concerns like auditing or request-scoped enrichment.
+ */
+const globalModelEvents = new ModelEvents();exports.ModelEvents=ModelEvents;exports.globalModelEvents=globalModelEvents;//# sourceMappingURL=model-events.js.map

package/cjs/events/model-events.js.map

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

package/cjs/expressions/aggregate-expressions.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Database-agnostic aggregation expressions.
+ *
+ * These helpers provide a unified API for building aggregate queries that work
+ * across different database types (MongoDB, PostgreSQL, MySQL, etc.).
+ *
+ * Each driver implementation translates these abstract expressions to their
+ * native format:
+ * - MongoDB: { $sum: 1 }, { $sum: "$field" }, etc.
+ * - SQL: COUNT(*), SUM(field), etc.
+ *
+ * @example
+ * ```typescript
+ * import { $agg } from '@warlock.js/cascade';
+ *
+ * // Works for both MongoDB and SQL
+ * Lesson.query()
+ *   .groupBy("type", {
+ *     count: $agg.count(),
+ *     total: $agg.sum("duration"),
+ *     avg: $agg.avg("rating")
+ *   })
+ *   .get();
+ * ```
+ */
+/**
+ * Abstract aggregate expression format.
+ *
+ * This format is database-agnostic and will be translated by each driver
+ * to their native syntax.
+ */
+export type AggregateExpression = {
+    /** The aggregate function type */
+    __agg: AggregateFunction;
+    /** The field to aggregate (null for count) */
+    __field: string | null;
+};
+/**
+ * Supported aggregate functions.
+ */
+export type AggregateFunction = "count" | "sum" | "avg" | "min" | "max" | "first" | "last" | "distinct" | "floor";
+/**
+ * Checks if a value is an abstract aggregate expression.
+ */
+export declare function isAggregateExpression(value: unknown): value is AggregateExpression;
+/**
+ * Database-agnostic aggregation expression helpers.
+ *
+ * These helpers create abstract expressions that each driver translates
+ * to their native format.
+ */
+export declare const $agg: {
+    /**
+     * Count documents in each group.
+     *
+     * @returns Abstract count expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   count: $agg.count()
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $sum: 1 }`
+     * - SQL: `COUNT(*)`
+     */
+    count(): AggregateExpression;
+    /**
+     * Sum a numeric field across documents in each group.
+     *
+     * @param field - The field name to sum
+     * @returns Abstract sum expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   totalDuration: $agg.sum("duration")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $sum: "$duration" }`
+     * - SQL: `SUM(duration)`
+     */
+    sum(field: string): AggregateExpression;
+    /**
+     * Calculate the average value of a field across documents in each group.
+     *
+     * @param field - The field name to average
+     * @returns Abstract average expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   avgRating: $agg.avg("rating")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $avg: "$rating" }`
+     * - SQL: `AVG(rating)`
+     */
+    avg(field: string): AggregateExpression;
+    /**
+     * Get the minimum value of a field across documents in each group.
+     *
+     * @param field - The field name
+     * @returns Abstract min expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   minPrice: $agg.min("price")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $min: "$price" }`
+     * - SQL: `MIN(price)`
+     */
+    min(field: string): AggregateExpression;
+    /**
+     * Get the maximum value of a field across documents in each group.
+     *
+     * @param field - The field name
+     * @returns Abstract max expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   maxPrice: $agg.max("price")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $max: "$price" }`
+     * - SQL: `MAX(price)`
+     */
+    max(field: string): AggregateExpression;
+    /**
+     * Get the distinct values of a field across documents in each group.
+     *
+     * @param field - The field name
+     * @returns Abstract distinct expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   distinctColors: $agg.distinct("color")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $distinct: "$color" }`
+     * - SQL: `DISTINCT(color)`
+     */
+    distinct(field: string): AggregateExpression;
+    /**
+     * Get the floor value of a field across documents in each group.
+     *
+     * @param field - The field name
+     * @returns Abstract floor expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   floorPrice: $agg.floor("price")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $floor: "$price" }`
+     * - SQL: `FLOOR(price)`
+     */
+    floor(field: string): AggregateExpression;
+    /**
+     * Get the first value of a field in each group (order-dependent).
+     *
+     * @param field - The field name
+     * @returns Abstract first expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   firstName: $agg.first("name")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $first: "$name" }`
+     * - SQL: `FIRST_VALUE(name) OVER (...)`
+     */
+    first(field: string): AggregateExpression;
+    /**
+     * Get the last value of a field in each group (order-dependent).
+     *
+     * @param field - The field name
+     * @returns Abstract last expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   lastName: $agg.last("name")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $last: "$name" }`
+     * - SQL: `LAST_VALUE(name) OVER (...)`
+     */
+    last(field: string): AggregateExpression;
+};
+//# sourceMappingURL=aggregate-expressions.d.ts.map

package/cjs/expressions/aggregate-expressions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate-expressions.d.ts","sourceRoot":"","sources":["../../src/expressions/aggregate-expressions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,kCAAkC;IAClC,KAAK,EAAE,iBAAiB,CAAC;IACzB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GACzB,OAAO,GACP,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,GACL,OAAO,GACP,MAAM,GACN,UAAU,GACV,OAAO,CAAC;AAEZ;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAOlF;AAED;;;;;GAKG;AACH,eAAO,MAAM,IAAI;IACf;;;;;;;;;;;;;;;OAeG;aACM,mBAAmB;IAI5B;;;;;;;;;;;;;;;;OAgBG;eACQ,MAAM,GAAG,mBAAmB;IAIvC;;;;;;;;;;;;;;;;OAgBG;eACQ,MAAM,GAAG,mBAAmB;IAIvC;;;;;;;;;;;;;;;;OAgBG;eACQ,MAAM,GAAG,mBAAmB;IAIvC;;;;;;;;;;;;;;;;OAgBG;eACQ,MAAM,GAAG,mBAAmB;IAIvC;;;;;;;;;;;;;;;;OAgBG;oBACa,MAAM,GAAG,mBAAmB;IAI5C;;;;;;;;;;;;;;;;OAgBG;iBACU,MAAM,GAAG,mBAAmB;IAIzC;;;;;;;;;;;;;;;;OAgBG;iBACU,MAAM,GAAG,mBAAmB;IAIzC;;;;;;;;;;;;;;;;OAgBG;gBACS,MAAM,GAAG,mBAAmB;CAGzC,CAAC"}

package/cjs/expressions/aggregate-expressions.js

@@ -0,0 +1,221 @@
+'use strict';/**
+ * Database-agnostic aggregation expressions.
+ *
+ * These helpers provide a unified API for building aggregate queries that work
+ * across different database types (MongoDB, PostgreSQL, MySQL, etc.).
+ *
+ * Each driver implementation translates these abstract expressions to their
+ * native format:
+ * - MongoDB: { $sum: 1 }, { $sum: "$field" }, etc.
+ * - SQL: COUNT(*), SUM(field), etc.
+ *
+ * @example
+ * ```typescript
+ * import { $agg } from '@warlock.js/cascade';
+ *
+ * // Works for both MongoDB and SQL
+ * Lesson.query()
+ *   .groupBy("type", {
+ *     count: $agg.count(),
+ *     total: $agg.sum("duration"),
+ *     avg: $agg.avg("rating")
+ *   })
+ *   .get();
+ * ```
+ */
+/**
+ * Checks if a value is an abstract aggregate expression.
+ */
+function isAggregateExpression(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "__field" in value &&
+        typeof value.__agg === "string");
+}
+/**
+ * Database-agnostic aggregation expression helpers.
+ *
+ * These helpers create abstract expressions that each driver translates
+ * to their native format.
+ */
+const $agg = {
+    /**
+     * Count documents in each group.
+     *
+     * @returns Abstract count expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   count: $agg.count()
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $sum: 1 }`
+     * - SQL: `COUNT(*)`
+     */
+    count() {
+        return { __agg: "count", __field: null };
+    },
+    /**
+     * Sum a numeric field across documents in each group.
+     *
+     * @param field - The field name to sum
+     * @returns Abstract sum expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   totalDuration: $agg.sum("duration")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $sum: "$duration" }`
+     * - SQL: `SUM(duration)`
+     */
+    sum(field) {
+        return { __agg: "sum", __field: field };
+    },
+    /**
+     * Calculate the average value of a field across documents in each group.
+     *
+     * @param field - The field name to average
+     * @returns Abstract average expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   avgRating: $agg.avg("rating")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $avg: "$rating" }`
+     * - SQL: `AVG(rating)`
+     */
+    avg(field) {
+        return { __agg: "avg", __field: field };
+    },
+    /**
+     * Get the minimum value of a field across documents in each group.
+     *
+     * @param field - The field name
+     * @returns Abstract min expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   minPrice: $agg.min("price")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $min: "$price" }`
+     * - SQL: `MIN(price)`
+     */
+    min(field) {
+        return { __agg: "min", __field: field };
+    },
+    /**
+     * Get the maximum value of a field across documents in each group.
+     *
+     * @param field - The field name
+     * @returns Abstract max expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   maxPrice: $agg.max("price")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $max: "$price" }`
+     * - SQL: `MAX(price)`
+     */
+    max(field) {
+        return { __agg: "max", __field: field };
+    },
+    /**
+     * Get the distinct values of a field across documents in each group.
+     *
+     * @param field - The field name
+     * @returns Abstract distinct expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   distinctColors: $agg.distinct("color")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $distinct: "$color" }`
+     * - SQL: `DISTINCT(color)`
+     */
+    distinct(field) {
+        return { __agg: "distinct", __field: field };
+    },
+    /**
+     * Get the floor value of a field across documents in each group.
+     *
+     * @param field - The field name
+     * @returns Abstract floor expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   floorPrice: $agg.floor("price")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $floor: "$price" }`
+     * - SQL: `FLOOR(price)`
+     */
+    floor(field) {
+        return { __agg: "floor", __field: field };
+    },
+    /**
+     * Get the first value of a field in each group (order-dependent).
+     *
+     * @param field - The field name
+     * @returns Abstract first expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   firstName: $agg.first("name")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $first: "$name" }`
+     * - SQL: `FIRST_VALUE(name) OVER (...)`
+     */
+    first(field) {
+        return { __agg: "first", __field: field };
+    },
+    /**
+     * Get the last value of a field in each group (order-dependent).
+     *
+     * @param field - The field name
+     * @returns Abstract last expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   lastName: $agg.last("name")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $last: "$name" }`
+     * - SQL: `LAST_VALUE(name) OVER (...)`
+     */
+    last(field) {
+        return { __agg: "last", __field: field };
+    },
+};exports.$agg=$agg;exports.isAggregateExpression=isAggregateExpression;//# sourceMappingURL=aggregate-expressions.js.map

package/cjs/expressions/aggregate-expressions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate-expressions.js","sources":["../../src/expressions/aggregate-expressions.ts"],"sourcesContent":[null],"names":[],"mappings":"aAAA;;;;;;;;;;;;;;;;;;;;;;;;AAwBG;AA6BH;;AAEG;AACG,SAAU,qBAAqB,CAAC,KAAc,EAAA;AAClD,IAAA,QACE,OAAO,KAAK,KAAK,QAAQ;AACzB,QAAA,KAAK,KAAK,IAAI;AACd,QAAA,SAAS,IAAI,KAAK;AAClB,QAAA,OAAQ,KAA6B,CAAC,KAAK,KAAK,QAAQ,EACxD;AACJ,CAAC;AAED;;;;;AAKG;AACU,MAAA,IAAI,GAAG;AAClB;;;;;;;;;;;;;;;AAeG;IACH,KAAK,GAAA;QACH,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;KAC1C;AAED;;;;;;;;;;;;;;;;AAgBG;AACH,IAAA,GAAG,CAAC,KAAa,EAAA;QACf,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;KACzC;AAED;;;;;;;;;;;;;;;;AAgBG;AACH,IAAA,GAAG,CAAC,KAAa,EAAA;QACf,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;KACzC;AAED;;;;;;;;;;;;;;;;AAgBG;AACH,IAAA,GAAG,CAAC,KAAa,EAAA;QACf,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;KACzC;AAED;;;;;;;;;;;;;;;;AAgBG;AACH,IAAA,GAAG,CAAC,KAAa,EAAA;QACf,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;KACzC;AAED;;;;;;;;;;;;;;;;AAgBG;AACH,IAAA,QAAQ,CAAC,KAAa,EAAA;QACpB,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;KAC9C;AAED;;;;;;;;;;;;;;;;AAgBG;AACH,IAAA,KAAK,CAAC,KAAa,EAAA;QACjB,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;KAC3C;AAED;;;;;;;;;;;;;;;;AAgBG;AACH,IAAA,KAAK,CAAC,KAAa,EAAA;QACjB,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;KAC3C;AAED;;;;;;;;;;;;;;;;AAgBG;AACH,IAAA,IAAI,CAAC,KAAa,EAAA;QAChB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;KAC1C;"}