@proseql/core 0.1.0

package/dist/storage/transforms.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Data transformation utilities for converting between internal formats
+ * (ReadonlyMap and array) and storage object format, plus collection
+ * file grouping utilities.
+ */
+/**
+ * Convert an array of entities with id fields to an object keyed by id.
+ * This provides O(1) lookups in storage files.
+ *
+ * @param items - Array of entities, each must have an 'id' field
+ * @returns Object keyed by entity id
+ *
+ * @example
+ * arrayToObject([
+ *   { id: 'user-1', name: 'Alice' },
+ *   { id: 'user-2', name: 'Bob' }
+ * ])
+ * // Returns: {
+ * //   'user-1': { id: 'user-1', name: 'Alice' },
+ * //   'user-2': { id: 'user-2', name: 'Bob' }
+ * // }
+ */
+export declare function arrayToObject<T extends {
+    id: string;
+}>(items: readonly T[]): Record<string, T>;
+/**
+ * Convert an object keyed by id back to an array of entities.
+ *
+ * @param obj - Object keyed by entity id
+ * @returns Array of entities
+ *
+ * @example
+ * objectToArray({
+ *   'user-1': { id: 'user-1', name: 'Alice' },
+ *   'user-2': { id: 'user-2', name: 'Bob' }
+ * })
+ * // Returns: [
+ * //   { id: 'user-1', name: 'Alice' },
+ * //   { id: 'user-2', name: 'Bob' }
+ * // ]
+ */
+export declare function objectToArray<T>(obj: Record<string, T>): T[];
+/**
+ * Collection configuration that may include a file path for persistence
+ */
+type CollectionConfig = {
+    readonly file?: string;
+    readonly [key: string]: unknown;
+};
+/**
+ * Group collections by their configured file paths.
+ * Collections without a file path are not included in the result.
+ *
+ * @param config - Database configuration with collection definitions
+ * @returns Map from file path to array of collection names that use that file
+ *
+ * @example
+ * groupByFile({
+ *   users: { schema: UserSchema, file: '/data/users.json' },
+ *   products: { schema: ProductSchema, file: '/data/db.json' },
+ *   categories: { schema: CategorySchema, file: '/data/db.json' },
+ *   sessions: { schema: SessionSchema } // no file = in-memory only
+ * })
+ * // Returns: Map {
+ * //   '/data/users.json' => ['users'],
+ * //   '/data/db.json' => ['products', 'categories']
+ * // }
+ */
+export declare function groupByFile<Config extends Record<string, CollectionConfig>>(config: Config): Map<string, string[]>;
+/**
+ * Get all unique file paths from a database configuration.
+ *
+ * @param config - Database configuration with collection definitions
+ * @returns Array of unique file paths used by collections
+ */
+export declare function getConfigFilePaths<Config extends Record<string, CollectionConfig>>(config: Config): string[];
+/**
+ * Check if a collection is configured for persistence.
+ *
+ * @param config - Database configuration
+ * @param collectionName - Name of the collection to check
+ * @returns True if the collection has a file path configured
+ */
+export declare function isCollectionPersistent<Config extends Record<string, CollectionConfig>>(config: Config, collectionName: keyof Config): boolean;
+/**
+ * Extract collections that should be stored in a specific file.
+ *
+ * @param data - Full dataset with all collections
+ * @param collectionsForFile - Array of collection names to extract
+ * @returns Object containing only the specified collections in object format
+ */
+export declare function extractCollectionsForFile<T extends Record<string, unknown[]>>(data: T, collectionsForFile: readonly string[]): Record<string, Record<string, unknown>>;
+/**
+ * Merge file data back into the main dataset.
+ * Converts object format back to array format for each collection.
+ *
+ * @param data - Current dataset to update
+ * @param fileData - Data loaded from file (in object format)
+ * @param collectionsFromFile - Array of collection names to update
+ * @returns Updated dataset with arrays
+ */
+export declare function mergeFileDataIntoDataset<T extends Record<string, unknown[]>>(data: T, fileData: Record<string, Record<string, unknown>>, collectionsFromFile: readonly string[]): T;
+/**
+ * Convert an array of entities to a ReadonlyMap keyed by entity ID.
+ *
+ * @param items - Array of entities, each must have an 'id' field
+ * @returns ReadonlyMap keyed by entity id
+ *
+ * @example
+ * arrayToMap([
+ *   { id: 'user-1', name: 'Alice' },
+ *   { id: 'user-2', name: 'Bob' }
+ * ])
+ * // Returns: Map { 'user-1' => { id: 'user-1', name: 'Alice' }, 'user-2' => { id: 'user-2', name: 'Bob' } }
+ */
+export declare function arrayToMap<T extends {
+    readonly id: string;
+}>(items: readonly T[]): ReadonlyMap<string, T>;
+/**
+ * Convert a ReadonlyMap to a Record keyed by entity ID (the on-disk object format).
+ *
+ * @param map - ReadonlyMap of entities keyed by ID
+ * @returns Record keyed by entity id
+ *
+ * @example
+ * mapToObject(new Map([
+ *   ['user-1', { id: 'user-1', name: 'Alice' }],
+ *   ['user-2', { id: 'user-2', name: 'Bob' }],
+ * ]))
+ * // Returns: { 'user-1': { id: 'user-1', name: 'Alice' }, 'user-2': { id: 'user-2', name: 'Bob' } }
+ */
+export declare function mapToObject<T>(map: ReadonlyMap<string, T>): Record<string, T>;
+/**
+ * Convert a Record keyed by entity ID to a ReadonlyMap.
+ * Inverse of mapToObject.
+ *
+ * @param obj - Record keyed by entity id
+ * @returns ReadonlyMap keyed by entity id
+ *
+ * @example
+ * objectToMap({
+ *   'user-1': { id: 'user-1', name: 'Alice' },
+ *   'user-2': { id: 'user-2', name: 'Bob' },
+ * })
+ * // Returns: Map { 'user-1' => { id: 'user-1', name: 'Alice' }, 'user-2' => { id: 'user-2', name: 'Bob' } }
+ */
+export declare function objectToMap<T>(obj: Readonly<Record<string, T>>): ReadonlyMap<string, T>;
+/**
+ * Convert a ReadonlyMap to an array of its values.
+ *
+ * @param map - ReadonlyMap of entities
+ * @returns Array of entity values
+ */
+export declare function mapToArray<T>(map: ReadonlyMap<string, T>): readonly T[];
+/**
+ * Extract collections from ReadonlyMap-based state for file storage.
+ *
+ * Takes a Record of collection name → ReadonlyMap and a list of collection
+ * names to include, returning nested Record format suitable for serialization.
+ *
+ * @param stateMaps - Record mapping collection names to their ReadonlyMap state
+ * @param collectionsForFile - Collection names to extract
+ * @returns Nested Record: { collectionName: { id: entity, ... }, ... }
+ */
+export declare function extractCollectionsFromMaps<T extends {
+    readonly id: string;
+}>(stateMaps: Readonly<Record<string, ReadonlyMap<string, T>>>, collectionsForFile: readonly string[]): Record<string, Record<string, T>>;
+/**
+ * Merge file data (nested Record format) back into ReadonlyMap-based state.
+ *
+ * Takes existing state maps, file data in Record format, and collection names,
+ * returning updated state maps with the file data merged in.
+ *
+ * @param stateMaps - Current state: Record of collection name → ReadonlyMap
+ * @param fileData - Data from file: { collectionName: { id: entity, ... }, ... }
+ * @param collectionsFromFile - Collection names to update from file data
+ * @returns Updated state maps
+ */
+export declare function mergeFileDataIntoMaps<T extends {
+    readonly id: string;
+}>(stateMaps: Readonly<Record<string, ReadonlyMap<string, T>>>, fileData: Readonly<Record<string, Readonly<Record<string, T>>>>, collectionsFromFile: readonly string[]): Record<string, ReadonlyMap<string, T>>;
+export {};
+//# sourceMappingURL=transforms.d.ts.map

package/dist/storage/transforms.d.ts.map

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

package/dist/storage/transforms.js

@@ -0,0 +1,263 @@
+/**
+ * Data transformation utilities for converting between internal formats
+ * (ReadonlyMap and array) and storage object format, plus collection
+ * file grouping utilities.
+ */
+/**
+ * Convert an array of entities with id fields to an object keyed by id.
+ * This provides O(1) lookups in storage files.
+ *
+ * @param items - Array of entities, each must have an 'id' field
+ * @returns Object keyed by entity id
+ *
+ * @example
+ * arrayToObject([
+ *   { id: 'user-1', name: 'Alice' },
+ *   { id: 'user-2', name: 'Bob' }
+ * ])
+ * // Returns: {
+ * //   'user-1': { id: 'user-1', name: 'Alice' },
+ * //   'user-2': { id: 'user-2', name: 'Bob' }
+ * // }
+ */
+export function arrayToObject(items) {
+    const result = {};
+    for (const item of items) {
+        if (typeof item.id !== "string") {
+            throw new Error(`Invalid entity: id must be a string, got ${typeof item.id}`);
+        }
+        result[item.id] = item;
+    }
+    return result;
+}
+/**
+ * Convert an object keyed by id back to an array of entities.
+ *
+ * @param obj - Object keyed by entity id
+ * @returns Array of entities
+ *
+ * @example
+ * objectToArray({
+ *   'user-1': { id: 'user-1', name: 'Alice' },
+ *   'user-2': { id: 'user-2', name: 'Bob' }
+ * })
+ * // Returns: [
+ * //   { id: 'user-1', name: 'Alice' },
+ * //   { id: 'user-2', name: 'Bob' }
+ * // ]
+ */
+export function objectToArray(obj) {
+    return Object.values(obj);
+}
+/**
+ * Group collections by their configured file paths.
+ * Collections without a file path are not included in the result.
+ *
+ * @param config - Database configuration with collection definitions
+ * @returns Map from file path to array of collection names that use that file
+ *
+ * @example
+ * groupByFile({
+ *   users: { schema: UserSchema, file: '/data/users.json' },
+ *   products: { schema: ProductSchema, file: '/data/db.json' },
+ *   categories: { schema: CategorySchema, file: '/data/db.json' },
+ *   sessions: { schema: SessionSchema } // no file = in-memory only
+ * })
+ * // Returns: Map {
+ * //   '/data/users.json' => ['users'],
+ * //   '/data/db.json' => ['products', 'categories']
+ * // }
+ */
+export function groupByFile(config) {
+    const fileGroups = new Map();
+    for (const [collectionName, collectionConfig] of Object.entries(config)) {
+        const filePath = collectionConfig.file;
+        if (filePath && typeof filePath === "string") {
+            const existingCollections = fileGroups.get(filePath) ?? [];
+            existingCollections.push(collectionName);
+            fileGroups.set(filePath, existingCollections);
+        }
+    }
+    return fileGroups;
+}
+/**
+ * Get all unique file paths from a database configuration.
+ *
+ * @param config - Database configuration with collection definitions
+ * @returns Array of unique file paths used by collections
+ */
+export function getConfigFilePaths(config) {
+    const filePaths = new Set();
+    for (const collectionConfig of Object.values(config)) {
+        if (collectionConfig.file && typeof collectionConfig.file === "string") {
+            filePaths.add(collectionConfig.file);
+        }
+    }
+    return Array.from(filePaths);
+}
+/**
+ * Check if a collection is configured for persistence.
+ *
+ * @param config - Database configuration
+ * @param collectionName - Name of the collection to check
+ * @returns True if the collection has a file path configured
+ */
+export function isCollectionPersistent(config, collectionName) {
+    const collectionConfig = config[collectionName];
+    return !!(collectionConfig?.file && typeof collectionConfig.file === "string");
+}
+/**
+ * Extract collections that should be stored in a specific file.
+ *
+ * @param data - Full dataset with all collections
+ * @param collectionsForFile - Array of collection names to extract
+ * @returns Object containing only the specified collections in object format
+ */
+export function extractCollectionsForFile(data, collectionsForFile) {
+    const result = {};
+    for (const collectionName of collectionsForFile) {
+        const collectionData = data[collectionName];
+        if (Array.isArray(collectionData)) {
+            // Validate that all items have string id fields
+            const validItems = collectionData.filter((item) => {
+                return (typeof item === "object" &&
+                    item !== null &&
+                    "id" in item &&
+                    typeof item.id === "string");
+            });
+            result[collectionName] = arrayToObject(validItems);
+        }
+    }
+    return result;
+}
+/**
+ * Merge file data back into the main dataset.
+ * Converts object format back to array format for each collection.
+ *
+ * @param data - Current dataset to update
+ * @param fileData - Data loaded from file (in object format)
+ * @param collectionsFromFile - Array of collection names to update
+ * @returns Updated dataset with arrays
+ */
+export function mergeFileDataIntoDataset(data, fileData, collectionsFromFile) {
+    const result = { ...data };
+    for (const collectionName of collectionsFromFile) {
+        const collectionFileData = fileData[collectionName];
+        if (collectionFileData && typeof collectionFileData === "object") {
+            // Convert back to array format
+            const arrayData = objectToArray(collectionFileData);
+            // Type-safe assignment using index signature constraint
+            if (collectionName in result) {
+                result[collectionName] = arrayData;
+            }
+        }
+    }
+    return result;
+}
+// ============================================================================
+// ReadonlyMap-aware transforms (Effect migration)
+// ============================================================================
+/**
+ * Convert an array of entities to a ReadonlyMap keyed by entity ID.
+ *
+ * @param items - Array of entities, each must have an 'id' field
+ * @returns ReadonlyMap keyed by entity id
+ *
+ * @example
+ * arrayToMap([
+ *   { id: 'user-1', name: 'Alice' },
+ *   { id: 'user-2', name: 'Bob' }
+ * ])
+ * // Returns: Map { 'user-1' => { id: 'user-1', name: 'Alice' }, 'user-2' => { id: 'user-2', name: 'Bob' } }
+ */
+export function arrayToMap(items) {
+    return new Map(items.map((item) => [item.id, item]));
+}
+/**
+ * Convert a ReadonlyMap to a Record keyed by entity ID (the on-disk object format).
+ *
+ * @param map - ReadonlyMap of entities keyed by ID
+ * @returns Record keyed by entity id
+ *
+ * @example
+ * mapToObject(new Map([
+ *   ['user-1', { id: 'user-1', name: 'Alice' }],
+ *   ['user-2', { id: 'user-2', name: 'Bob' }],
+ * ]))
+ * // Returns: { 'user-1': { id: 'user-1', name: 'Alice' }, 'user-2': { id: 'user-2', name: 'Bob' } }
+ */
+export function mapToObject(map) {
+    const result = {};
+    for (const [key, value] of map) {
+        result[key] = value;
+    }
+    return result;
+}
+/**
+ * Convert a Record keyed by entity ID to a ReadonlyMap.
+ * Inverse of mapToObject.
+ *
+ * @param obj - Record keyed by entity id
+ * @returns ReadonlyMap keyed by entity id
+ *
+ * @example
+ * objectToMap({
+ *   'user-1': { id: 'user-1', name: 'Alice' },
+ *   'user-2': { id: 'user-2', name: 'Bob' },
+ * })
+ * // Returns: Map { 'user-1' => { id: 'user-1', name: 'Alice' }, 'user-2' => { id: 'user-2', name: 'Bob' } }
+ */
+export function objectToMap(obj) {
+    return new Map(Object.entries(obj));
+}
+/**
+ * Convert a ReadonlyMap to an array of its values.
+ *
+ * @param map - ReadonlyMap of entities
+ * @returns Array of entity values
+ */
+export function mapToArray(map) {
+    return Array.from(map.values());
+}
+/**
+ * Extract collections from ReadonlyMap-based state for file storage.
+ *
+ * Takes a Record of collection name → ReadonlyMap and a list of collection
+ * names to include, returning nested Record format suitable for serialization.
+ *
+ * @param stateMaps - Record mapping collection names to their ReadonlyMap state
+ * @param collectionsForFile - Collection names to extract
+ * @returns Nested Record: { collectionName: { id: entity, ... }, ... }
+ */
+export function extractCollectionsFromMaps(stateMaps, collectionsForFile) {
+    const result = {};
+    for (const collectionName of collectionsForFile) {
+        const collectionMap = stateMaps[collectionName];
+        if (collectionMap !== undefined) {
+            result[collectionName] = mapToObject(collectionMap);
+        }
+    }
+    return result;
+}
+/**
+ * Merge file data (nested Record format) back into ReadonlyMap-based state.
+ *
+ * Takes existing state maps, file data in Record format, and collection names,
+ * returning updated state maps with the file data merged in.
+ *
+ * @param stateMaps - Current state: Record of collection name → ReadonlyMap
+ * @param fileData - Data from file: { collectionName: { id: entity, ... }, ... }
+ * @param collectionsFromFile - Collection names to update from file data
+ * @returns Updated state maps
+ */
+export function mergeFileDataIntoMaps(stateMaps, fileData, collectionsFromFile) {
+    const result = { ...stateMaps };
+    for (const collectionName of collectionsFromFile) {
+        const collectionFileData = fileData[collectionName];
+        if (collectionFileData !== undefined) {
+            result[collectionName] = objectToMap(collectionFileData);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=transforms.js.map

package/dist/storage/transforms.js.map

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

package/dist/transactions/transaction.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Transaction support for atomic multi-collection operations.
+ *
+ * `createTransaction` returns a TransactionContext with collection accessors,
+ * commit/rollback methods, and mutation tracking. Mutations are visible
+ * immediately within the transaction (read-own-writes) and either committed
+ * atomically or rolled back to pre-transaction state.
+ *
+ * `$transaction` is a callback wrapper that auto-commits on success and
+ * auto-rolls back on failure.
+ */
+import { Effect, PubSub, Ref } from "effect";
+import { TransactionError } from "../errors/crud-errors.js";
+import type { EffectCollection } from "../factories/database-effect.js";
+import type { TransactionContext } from "../types/crud-types.js";
+import type { ChangeEvent } from "../types/reactive-types.js";
+type HasId = {
+    readonly id: string;
+};
+/**
+ * Internal ref map type used for cross-collection references.
+ */
+type StateRefs = Record<string, Ref.Ref<ReadonlyMap<string, HasId>>>;
+/**
+ * Persistence trigger interface for scheduling debounced saves.
+ */
+interface PersistenceTrigger {
+    /** Schedule a debounced save for the given key */
+    readonly schedule: (key: string) => void;
+}
+/**
+ * Callback type for building a collection with transaction-aware afterMutation.
+ * The afterMutation adds the collection name to the mutation set instead of
+ * scheduling a persistence write.
+ */
+type BuildCollectionForTx = (collectionName: string, addMutation: (name: string) => void) => EffectCollection<HasId>;
+/**
+ * Create a new transaction context.
+ *
+ * Parameters:
+ * - stateRefs: The database's collection Refs (will be snapshotted and potentially restored)
+ * - transactionLock: Single-writer lock Ref (prevents concurrent transactions)
+ * - buildCollectionForTx: Callback to create collection accessors with transaction-aware mutations
+ * - persistenceTrigger: Optional trigger for scheduling saves on commit
+ * - changePubSub: Optional PubSub for reactive change notifications. When provided,
+ *   individual mutation events are suppressed during the transaction and a single
+ *   batch event is published for each mutated collection on commit.
+ *
+ * Returns an Effect that yields a TransactionContext. The context provides:
+ * - Collection accessors with the same interface as db.collectionName
+ * - commit() to finalize changes and trigger persistence
+ * - rollback() to restore snapshots and discard changes
+ * - isActive to check if transaction is still open
+ * - mutatedCollections to see which collections were written to
+ *
+ * On failure (e.g., lock already held), returns TransactionError.
+ */
+export declare const createTransaction: <DB extends Record<string, EffectCollection<HasId>>>(stateRefs: StateRefs, transactionLock: Ref.Ref<boolean>, buildCollectionForTx: BuildCollectionForTx, persistenceTrigger?: PersistenceTrigger, changePubSub?: PubSub.PubSub<ChangeEvent>) => Effect.Effect<TransactionContext<DB>, TransactionError>;
+/**
+ * Execute a callback within an atomic transaction context.
+ *
+ * All CRUD operations inside the callback operate against the live in-memory state.
+ * On success, changes are committed and persistence is triggered.
+ * On failure (error thrown or explicit rollback), all mutations are reverted.
+ *
+ * Usage:
+ * ```ts
+ * const result = await db.$transaction((ctx) =>
+ *   Effect.gen(function* () {
+ *     const user = yield* ctx.users.create({ name: "Alice" })
+ *     const post = yield* ctx.posts.create({ authorId: user.id, title: "Hello" })
+ *     return { user, post }
+ *   })
+ * ).pipe(Effect.runPromise)
+ * ```
+ *
+ * @param stateRefs - The database's collection Refs
+ * @param transactionLock - Single-writer lock Ref
+ * @param buildCollectionForTx - Callback to create collection accessors
+ * @param persistenceTrigger - Optional trigger for scheduling saves on commit
+ * @param changePubSub - Optional PubSub for reactive change notifications
+ * @param fn - The callback to execute within the transaction
+ * @returns Effect that yields the callback result, with TransactionError in error channel
+ */
+export declare const $transaction: <DB extends Record<string, EffectCollection<HasId>>, A, E>(stateRefs: StateRefs, transactionLock: Ref.Ref<boolean>, buildCollectionForTx: BuildCollectionForTx, persistenceTrigger: PersistenceTrigger | undefined, changePubSub: PubSub.PubSub<ChangeEvent> | undefined, fn: (ctx: TransactionContext<DB>) => Effect.Effect<A, E>) => Effect.Effect<A, E | TransactionError>;
+export {};
+//# sourceMappingURL=transaction.d.ts.map

package/dist/transactions/transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../src/transactions/transaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAM9D,KAAK,KAAK,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAErC;;GAEG;AACH,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;AAErE;;GAEG;AACH,UAAU,kBAAkB;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED;;;;GAIG;AACH,KAAK,oBAAoB,GAAG,CAC3B,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,KAC/B,gBAAgB,CAAC,KAAK,CAAC,CAAC;AAM7B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,iBAAiB,GAC7B,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,KAAK,CAAC,CAAC,EAElD,WAAW,SAAS,EACpB,iBAAiB,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,EACjC,sBAAsB,oBAAoB,EAC1C,qBAAqB,kBAAkB,EACvC,eAAe,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,KACvC,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,EAAE,CAAC,EAAE,gBAAgB,CAwLtD,CAAC;AAMJ;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,YAAY,GACxB,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,KAAK,CAAC,CAAC,EAClD,CAAC,EACD,CAAC,EAED,WAAW,SAAS,EACpB,iBAAiB,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,EACjC,sBAAsB,oBAAoB,EAC1C,oBAAoB,kBAAkB,GAAG,SAAS,EAClD,cAAc,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,GAAG,SAAS,EACpD,IAAI,CAAC,GAAG,EAAE,kBAAkB,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KACtD,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,gBAAgB,CAgDrC,CAAC"}