web-idb-client 1.0.0

package/dist/query/order.d.ts

@@ -0,0 +1,8 @@
+import type { LooseOrderByInputInterface } from '../schema/infer';
+import type { StoreInterface } from '../schema/types';
+export interface ResolvedOrderInterface {
+    direction: IDBCursorDirection;
+    /** If set, iterate via this index; otherwise via PK */
+    indexName?: string;
+}
+export declare function resolveOrderBy(store: StoreInterface, orderBy?: LooseOrderByInputInterface): ResolvedOrderInterface | null;

package/dist/query/order.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveOrderBy = void 0;
+const errors_1 = require("../errors");
+function resolveOrderBy(store, orderBy) {
+    var _a;
+    if (!orderBy) {
+        return null;
+    }
+    const keys = Object.keys(orderBy);
+    if (keys.length === 0) {
+        return null;
+    }
+    if (keys.length > 1) {
+        throw new errors_1.IndexedDbError('QUERY_INVALID', 'orderBy supports a single field in v2', { store: store.name });
+    }
+    const field = keys[0];
+    const dir = (_a = orderBy[field]) !== null && _a !== void 0 ? _a : 'asc';
+    const direction = dir === 'desc' ? 'prev' : 'next';
+    if (field === store.primaryKey.keyPath) {
+        return { direction };
+    }
+    const index = store.indexes.find((i) => i.name === field || i.keyPath === field);
+    if (!index) {
+        throw new errors_1.IndexedDbError('QUERY_INVALID', `orderBy field "${field}" is not indexed on store "${store.name}"`, { store: store.name, field });
+    }
+    return { direction, indexName: index.name };
+}
+exports.resolveOrderBy = resolveOrderBy;
+//# sourceMappingURL=order.js.map

package/dist/query/order.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"order.js","sourceRoot":"","sources":["../../src/query/order.ts"],"names":[],"mappings":";;;AAEA,sCAA2C;AAQ3C,SAAgB,cAAc,CAC5B,KAAqB,EACrB,OAAoC;;IAEpC,IAAI,CAAC,OAAO,EAAE;QACZ,OAAO,IAAI,CAAC;KACb;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAClC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE;QACrB,OAAO,IAAI,CAAC;KACb;IACD,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE;QACnB,MAAM,IAAI,uBAAc,CACtB,eAAe,EACf,uCAAuC,EACvC,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,CACtB,CAAC;KACH;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACtB,MAAM,GAAG,GAAmB,MAAA,OAAO,CAAC,KAAK,CAAC,mCAAI,KAAK,CAAC;IACpD,MAAM,SAAS,GAAuB,GAAG,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;IAEvE,IAAI,KAAK,KAAK,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE;QACtC,OAAO,EAAE,SAAS,EAAE,CAAC;KACtB;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAC9B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,OAAO,KAAK,KAAK,CAC/C,CAAC;IACF,IAAI,CAAC,KAAK,EAAE;QACV,MAAM,IAAI,uBAAc,CACtB,eAAe,EACf,kBAAkB,KAAK,8BAA8B,KAAK,CAAC,IAAI,GAAG,EAClE,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAC7B,CAAC;KACH;IACD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;AAC9C,CAAC;AArCD,wCAqCC"}

package/dist/query/where.d.ts

@@ -0,0 +1,17 @@
+import type { StoreInterface } from '../schema/types';
+import type { LooseWhereInputInterface } from '../schema/infer';
+export interface ResolvedQueryInterface {
+    /** Use object store directly (PK) vs named index */
+    source: 'store' | 'index';
+    indexName?: string;
+    keyRange?: IDBKeyRange | IDBValidKey;
+}
+/**
+ * Resolve a where object to a single index/store lookup.
+ * Multi-key where is only supported when it matches a compound index exactly.
+ * Named compound: `{ byUserDue: [userId, dueAt] }`.
+ */
+export declare function resolveWhere(store: StoreInterface, where?: LooseWhereInputInterface): ResolvedQueryInterface;
+export declare function isUniqueTarget(store: StoreInterface, where: LooseWhereInputInterface): boolean;
+/** Whether where and orderBy would require different IDB sources. */
+export declare function orderConflictsWithWhere(_store: StoreInterface, resolved: ResolvedQueryInterface, orderIndexName: string | undefined): boolean;

package/dist/query/where.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.orderConflictsWithWhere = exports.isUniqueTarget = exports.resolveWhere = void 0;
+const key_range_1 = require("../utils/key-range");
+const errors_1 = require("../errors");
+function resolveIndexName(store, whereKey) {
+    if (whereKey === store.primaryKey.keyPath ||
+        (whereKey === 'id' && store.primaryKey.keyPath === 'id')) {
+        return { source: 'store' };
+    }
+    const byName = store.indexes.find((i) => i.name === whereKey);
+    if (byName) {
+        return { source: 'index', indexName: byName.name };
+    }
+    const byField = store.indexes.find((i) => typeof i.keyPath === 'string' && i.keyPath === whereKey);
+    if (byField) {
+        return { source: 'index', indexName: byField.name };
+    }
+    throw new errors_1.IndexedDbError('QUERY_INVALID', `Field or index "${whereKey}" is not indexed on store "${store.name}". Declare it with .index() / compoundIndex() in the schema.`, { store: store.name, field: whereKey });
+}
+function resolveNamedCompound(store, indexName, value) {
+    const compound = store.indexes.find((i) => i.name === indexName && Array.isArray(i.keyPath));
+    if (!compound || !Array.isArray(compound.keyPath)) {
+        return null;
+    }
+    if (!Array.isArray(value)) {
+        throw new errors_1.IndexedDbError('QUERY_INVALID', `Compound index "${indexName}" expects an array of key parts`, { store: store.name, index: indexName });
+    }
+    if (value.length !== compound.keyPath.length) {
+        throw new errors_1.IndexedDbError('QUERY_INVALID', `Compound index "${indexName}" expects ${compound.keyPath.length} key parts, got ${value.length}`, { store: store.name, index: indexName });
+    }
+    return {
+        source: 'index',
+        indexName: compound.name,
+        keyRange: (0, key_range_1.toCompoundKeyRange)(value),
+    };
+}
+/**
+ * Resolve a where object to a single index/store lookup.
+ * Multi-key where is only supported when it matches a compound index exactly.
+ * Named compound: `{ byUserDue: [userId, dueAt] }`.
+ */
+function resolveWhere(store, where) {
+    if (!where || Object.keys(where).length === 0) {
+        return { source: 'store' };
+    }
+    const keys = Object.keys(where);
+    if (keys.length === 1) {
+        const key = keys[0];
+        const value = where[key];
+        const namedCompound = resolveNamedCompound(store, key, value);
+        if (namedCompound) {
+            return namedCompound;
+        }
+        const target = resolveIndexName(store, key);
+        return Object.assign(Object.assign({}, target), { keyRange: (0, key_range_1.toKeyRange)(value) });
+    }
+    // Compound: prefer an index whose keyPath matches all keys (order-sensitive)
+    const compound = store.indexes.find((i) => Array.isArray(i.keyPath) &&
+        i.keyPath.length === keys.length &&
+        i.keyPath.every((k) => keys.includes(k)));
+    if (compound && Array.isArray(compound.keyPath)) {
+        const parts = compound.keyPath.map((k) => {
+            const v = where[k];
+            if (v === undefined) {
+                throw new errors_1.IndexedDbError('QUERY_INVALID', `Missing compound key part "${k}"`, { store: store.name, index: compound.name, field: k });
+            }
+            return v;
+        });
+        return {
+            source: 'index',
+            indexName: compound.name,
+            keyRange: (0, key_range_1.toCompoundKeyRange)(parts),
+        };
+    }
+    throw new errors_1.IndexedDbError('QUERY_INVALID', `Cannot resolve where keys [${keys.join(', ')}] to a single index on "${store.name}". Use one indexed field or a declared compound index.`, { store: store.name });
+}
+exports.resolveWhere = resolveWhere;
+function isUniqueTarget(store, where) {
+    const keys = Object.keys(where);
+    if (keys.length !== 1) {
+        return false;
+    }
+    const key = keys[0];
+    if (key === store.primaryKey.keyPath) {
+        return true;
+    }
+    const index = store.indexes.find((i) => i.name === key || i.keyPath === key);
+    return Boolean(index === null || index === void 0 ? void 0 : index.unique);
+}
+exports.isUniqueTarget = isUniqueTarget;
+/** Whether where and orderBy would require different IDB sources. */
+function orderConflictsWithWhere(_store, resolved, orderIndexName) {
+    if (!orderIndexName) {
+        // orderBy PK: conflicts when where uses a secondary index
+        return resolved.source === 'index' && Boolean(resolved.indexName);
+    }
+    if (resolved.source === 'store') {
+        // No where / empty where → iterate the orderBy index freely.
+        // PK keyRange where + secondary orderBy → needs sortInMemory.
+        return resolved.keyRange !== undefined;
+    }
+    return Boolean(resolved.indexName && resolved.indexName !== orderIndexName);
+}
+exports.orderConflictsWithWhere = orderConflictsWithWhere;
+//# sourceMappingURL=where.js.map

package/dist/query/where.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"where.js","sourceRoot":"","sources":["../../src/query/where.ts"],"names":[],"mappings":";;;AAEA,kDAAoE;AACpE,sCAA2C;AAS3C,SAAS,gBAAgB,CACvB,KAAqB,EACrB,QAAgB;IAEhB,IACE,QAAQ,KAAK,KAAK,CAAC,UAAU,CAAC,OAAO;QACrC,CAAC,QAAQ,KAAK,IAAI,IAAI,KAAK,CAAC,UAAU,CAAC,OAAO,KAAK,IAAI,CAAC,EACxD;QACA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;KAC5B;IAED,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;IAC9D,IAAI,MAAM,EAAE;QACV,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;KACpD;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAChC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO,KAAK,QAAQ,CAC/D,CAAC;IACF,IAAI,OAAO,EAAE;QACX,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;KACrD;IAED,MAAM,IAAI,uBAAc,CACtB,eAAe,EACf,mBAAmB,QAAQ,8BAA8B,KAAK,CAAC,IAAI,8DAA8D,EACjI,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CACvC,CAAC;AACJ,CAAC;AAED,SAAS,oBAAoB,CAC3B,KAAqB,EACrB,SAAiB,EACjB,KAAc;IAEd,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CACjC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CACxD,CAAC;IACF,IAAI,CAAC,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE;QACjD,OAAO,IAAI,CAAC;KACb;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE;QACzB,MAAM,IAAI,uBAAc,CACtB,eAAe,EACf,mBAAmB,SAAS,iCAAiC,EAC7D,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CACxC,CAAC;KACH;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE;QAC5C,MAAM,IAAI,uBAAc,CACtB,eAAe,EACf,mBAAmB,SAAS,aAAa,QAAQ,CAAC,OAAO,CAAC,MAAM,mBAAmB,KAAK,CAAC,MAAM,EAAE,EACjG,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CACxC,CAAC;KACH;IACD,OAAO;QACL,MAAM,EAAE,OAAO;QACf,SAAS,EAAE,QAAQ,CAAC,IAAI;QACxB,QAAQ,EAAE,IAAA,8BAAkB,EAAC,KAAK,CAAC;KACpC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAgB,YAAY,CAC1B,KAAqB,EACrB,KAAgC;IAEhC,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE;QAC7C,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;KAC5B;IAED,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAEhC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE;QACrB,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QACzB,MAAM,aAAa,GAAG,oBAAoB,CAAC,KAAK,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;QAC9D,IAAI,aAAa,EAAE;YACjB,OAAO,aAAa,CAAC;SACtB;QACD,MAAM,MAAM,GAAG,gBAAgB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC5C,uCACK,MAAM,KACT,QAAQ,EAAE,IAAA,sBAAU,EAAC,KAAM,CAAC,IAC5B;KACH;IAED,6EAA6E;IAC7E,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CACjC,CAAC,CAAC,EAAE,EAAE,CACJ,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;QACxB,CAAC,CAAC,OAAO,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM;QAChC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAC3C,CAAC;IAEF,IAAI,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE;QAC/C,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YACvC,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;YACnB,IAAI,CAAC,KAAK,SAAS,EAAE;gBACnB,MAAM,IAAI,uBAAc,CACtB,eAAe,EACf,8BAA8B,CAAC,GAAG,EAClC,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CACtD,CAAC;aACH;YACD,OAAO,CAAC,CAAC;QACX,CAAC,CAAC,CAAC;QACH,OAAO;YACL,MAAM,EAAE,OAAO;YACf,SAAS,EAAE,QAAQ,CAAC,IAAI;YACxB,QAAQ,EAAE,IAAA,8BAAkB,EAAC,KAAK,CAAC;SACpC,CAAC;KACH;IAED,MAAM,IAAI,uBAAc,CACtB,eAAe,EACf,8BAA8B,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,2BAA2B,KAAK,CAAC,IAAI,wDAAwD,EAC1I,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,CACtB,CAAC;AACJ,CAAC;AAxDD,oCAwDC;AAED,SAAgB,cAAc,CAC5B,KAAqB,EACrB,KAA+B;IAE/B,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAChC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE;QACrB,OAAO,KAAK,CAAC;KACd;IACD,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,IAAI,GAAG,KAAK,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE;QACpC,OAAO,IAAI,CAAC;KACb;IACD,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAC9B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,IAAI,CAAC,CAAC,OAAO,KAAK,GAAG,CAC3C,CAAC;IACF,OAAO,OAAO,CAAC,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,MAAM,CAAC,CAAC;AAChC,CAAC;AAhBD,wCAgBC;AAED,qEAAqE;AACrE,SAAgB,uBAAuB,CACrC,MAAsB,EACtB,QAAgC,EAChC,cAAkC;IAElC,IAAI,CAAC,cAAc,EAAE;QACnB,0DAA0D;QAC1D,OAAO,QAAQ,CAAC,MAAM,KAAK,OAAO,IAAI,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;KACnE;IACD,IAAI,QAAQ,CAAC,MAAM,KAAK,OAAO,EAAE;QAC/B,6DAA6D;QAC7D,8DAA8D;QAC9D,OAAO,QAAQ,CAAC,QAAQ,KAAK,SAAS,CAAC;KACxC;IACD,OAAO,OAAO,CAAC,QAAQ,CAAC,SAAS,IAAI,QAAQ,CAAC,SAAS,KAAK,cAAc,CAAC,CAAC;AAC9E,CAAC;AAfD,0DAeC"}

package/dist/relation/define-relation.d.ts

@@ -0,0 +1,49 @@
+import type { DbStoresInterface, StoreInterface } from '../schema/types';
+export type RelationType = 'hasMany' | 'belongsTo';
+export interface RelationEndpoint {
+    store: string;
+    /** FK or PK field name on that store */
+    field: string;
+}
+/**
+ * Declarative relation metadata for docs / validation.
+ * Does **not** enable Prisma-style `include` — use `loadMany` / `loadOne`.
+ */
+export interface RelationInterface {
+    name: string;
+    type: RelationType;
+    /**
+     * hasMany: parent side (PK). belongsTo: child side (FK field on this store).
+     */
+    from: RelationEndpoint;
+    /**
+     * hasMany: child side (FK field). belongsTo: parent side (PK).
+     */
+    to: RelationEndpoint;
+}
+/**
+ * Typed relation endpoint from a store + field key (avoids store/field typos).
+ *
+ * ```ts
+ * relation({
+ *   name: 'tasksOfUser',
+ *   type: 'hasMany',
+ *   from: end(users, 'id'),
+ *   to: end(tasks, 'userId'),
+ * })
+ * ```
+ */
+export declare function end<TStore extends StoreInterface, TField extends keyof TStore['fields'] & string>(store: TStore, field: TField): RelationEndpoint;
+export declare function relation(def: RelationInterface): RelationInterface;
+/**
+ * Ensure every `.ref()` field is indexed (or is the PK), and that the
+ * target store exists when `stores` is provided.
+ */
+export declare function assertRefsValid(store: StoreInterface, stores?: DbStoresInterface): void;
+/**
+ * Validate a `relation()` against store map: endpoints exist and the FK
+ * side is indexed.
+ */
+export declare function assertRelationValid(rel: RelationInterface, stores: DbStoresInterface): void;
+/** Validate all `.ref()` fields across a client store map. */
+export declare function assertAllRefsValid(stores: DbStoresInterface): void;

package/dist/relation/define-relation.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertAllRefsValid = exports.assertRelationValid = exports.assertRefsValid = exports.relation = exports.end = void 0;
+const errors_1 = require("../errors");
+/**
+ * Typed relation endpoint from a store + field key (avoids store/field typos).
+ *
+ * ```ts
+ * relation({
+ *   name: 'tasksOfUser',
+ *   type: 'hasMany',
+ *   from: end(users, 'id'),
+ *   to: end(tasks, 'userId'),
+ * })
+ * ```
+ */
+function end(store, field) {
+    if (!(field in store.fields)) {
+        throw new errors_1.IndexedDbError('SCHEMA_INVALID', `end(): store "${store.name}" has no field "${field}"`, { store: store.name, field });
+    }
+    return { store: store.name, field };
+}
+exports.end = end;
+function relation(def) {
+    if (!def.name) {
+        throw new errors_1.IndexedDbError('SCHEMA_INVALID', 'relation() requires a name');
+    }
+    if (def.type !== 'hasMany' && def.type !== 'belongsTo') {
+        throw new errors_1.IndexedDbError('SCHEMA_INVALID', `relation "${def.name}": type must be "hasMany" or "belongsTo"`);
+    }
+    return def;
+}
+exports.relation = relation;
+function isQueryableField(store, fieldName) {
+    if (store.primaryKey.keyPath === fieldName) {
+        return true;
+    }
+    return store.indexes.some((i) => i.name === fieldName ||
+        (typeof i.keyPath === 'string' && i.keyPath === fieldName));
+}
+/**
+ * Ensure every `.ref()` field is indexed (or is the PK), and that the
+ * target store exists when `stores` is provided.
+ */
+function assertRefsValid(store, stores) {
+    for (const [fieldName, fieldDef] of Object.entries(store.fields)) {
+        const ref = fieldDef.meta.ref;
+        if (!ref) {
+            continue;
+        }
+        if (!isQueryableField(store, fieldName)) {
+            throw new errors_1.IndexedDbError('SCHEMA_INVALID', `Store "${store.name}" field "${fieldName}" has .ref("${ref.store}") but is not indexed. Chain .index() / .uniqueIndex() so FK lookups use an IDB index.`, { store: store.name, field: fieldName });
+        }
+        if (stores) {
+            const byName = new Map(Object.values(stores).map((s) => [s.name, s]));
+            if (!byName.has(ref.store)) {
+                throw new errors_1.IndexedDbError('SCHEMA_INVALID', `Store "${store.name}" field "${fieldName}" refs unknown store "${ref.store}". Known: ${[...byName.keys()].join(', ') || '(none)'}`, { store: store.name, field: fieldName });
+            }
+        }
+    }
+}
+exports.assertRefsValid = assertRefsValid;
+/**
+ * Validate a `relation()` against store map: endpoints exist and the FK
+ * side is indexed.
+ */
+function assertRelationValid(rel, stores) {
+    const byName = new Map(Object.values(stores).map((s) => [s.name, s]));
+    const fromStore = byName.get(rel.from.store);
+    const toStore = byName.get(rel.to.store);
+    if (!fromStore) {
+        throw new errors_1.IndexedDbError('SCHEMA_INVALID', `relation "${rel.name}": unknown from.store "${rel.from.store}"`);
+    }
+    if (!toStore) {
+        throw new errors_1.IndexedDbError('SCHEMA_INVALID', `relation "${rel.name}": unknown to.store "${rel.to.store}"`);
+    }
+    if (!(rel.from.field in fromStore.fields)) {
+        throw new errors_1.IndexedDbError('SCHEMA_INVALID', `relation "${rel.name}": from.field "${rel.from.field}" missing on "${rel.from.store}"`, { store: rel.from.store, field: rel.from.field });
+    }
+    if (!(rel.to.field in toStore.fields)) {
+        throw new errors_1.IndexedDbError('SCHEMA_INVALID', `relation "${rel.name}": to.field "${rel.to.field}" missing on "${rel.to.store}"`, { store: rel.to.store, field: rel.to.field });
+    }
+    // FK must be indexed: hasMany → to.field on child; belongsTo → from.field on child
+    if (rel.type === 'hasMany') {
+        if (!isQueryableField(toStore, rel.to.field)) {
+            throw new errors_1.IndexedDbError('SCHEMA_INVALID', `relation "${rel.name}" (hasMany): FK "${rel.to.store}.${rel.to.field}" must be indexed`, { store: rel.to.store, field: rel.to.field });
+        }
+    }
+    else if (!isQueryableField(fromStore, rel.from.field)) {
+        throw new errors_1.IndexedDbError('SCHEMA_INVALID', `relation "${rel.name}" (belongsTo): FK "${rel.from.store}.${rel.from.field}" must be indexed`, { store: rel.from.store, field: rel.from.field });
+    }
+}
+exports.assertRelationValid = assertRelationValid;
+/** Validate all `.ref()` fields across a client store map. */
+function assertAllRefsValid(stores) {
+    for (const store of Object.values(stores)) {
+        assertRefsValid(store, stores);
+    }
+}
+exports.assertAllRefsValid = assertAllRefsValid;
+//# sourceMappingURL=define-relation.js.map

package/dist/relation/define-relation.js.map

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

package/dist/relation/index.d.ts

@@ -0,0 +1,3 @@
+export { relation, end, assertRefsValid, assertRelationValid, assertAllRefsValid, } from './define-relation';
+export type { RelationInterface, RelationType, RelationEndpoint, } from './define-relation';
+export { loadMany, loadOne, findByForeignKey } from './load-related';

package/dist/relation/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findByForeignKey = exports.loadOne = exports.loadMany = exports.assertAllRefsValid = exports.assertRelationValid = exports.assertRefsValid = exports.end = exports.relation = void 0;
+var define_relation_1 = require("./define-relation");
+Object.defineProperty(exports, "relation", { enumerable: true, get: function () { return define_relation_1.relation; } });
+Object.defineProperty(exports, "end", { enumerable: true, get: function () { return define_relation_1.end; } });
+Object.defineProperty(exports, "assertRefsValid", { enumerable: true, get: function () { return define_relation_1.assertRefsValid; } });
+Object.defineProperty(exports, "assertRelationValid", { enumerable: true, get: function () { return define_relation_1.assertRelationValid; } });
+Object.defineProperty(exports, "assertAllRefsValid", { enumerable: true, get: function () { return define_relation_1.assertAllRefsValid; } });
+var load_related_1 = require("./load-related");
+Object.defineProperty(exports, "loadMany", { enumerable: true, get: function () { return load_related_1.loadMany; } });
+Object.defineProperty(exports, "loadOne", { enumerable: true, get: function () { return load_related_1.loadOne; } });
+Object.defineProperty(exports, "findByForeignKey", { enumerable: true, get: function () { return load_related_1.findByForeignKey; } });
+//# sourceMappingURL=index.js.map

package/dist/relation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/relation/index.ts"],"names":[],"mappings":";;;AAAA,qDAM2B;AALzB,2GAAA,QAAQ,OAAA;AACR,sGAAA,GAAG,OAAA;AACH,kHAAA,eAAe,OAAA;AACf,sHAAA,mBAAmB,OAAA;AACnB,qHAAA,kBAAkB,OAAA;AAOpB,+CAAqE;AAA5D,wGAAA,QAAQ,OAAA;AAAE,uGAAA,OAAO,OAAA;AAAE,gHAAA,gBAAgB,OAAA"}

package/dist/relation/load-related.d.ts

@@ -0,0 +1,21 @@
+import type { Store } from '../client/store';
+import type { StoreInterface } from '../schema/types';
+import type { InferSelect } from '../schema/infer';
+/**
+ * Load many child rows by foreign key (`hasMany`).
+ *
+ * Explicit helper — not Prisma `include`. Prefer calling inside
+ * `transaction()` when loading parent + children together.
+ *
+ * **N+1:** calling this once per parent in a loop hits the index once per
+ * parent. For many parents, prefer one `findMany` + group in memory, or
+ * accept the N+1 cost for small sets.
+ */
+export declare function loadMany<TStore extends StoreInterface>(childStore: Store<TStore>, foreignKey: keyof TStore['fields'] & string, parentKey: IDBValidKey): Promise<InferSelect<TStore>[]>;
+/**
+ * Load one parent row by primary key (`belongsTo`).
+ * Pass the FK value from the child row.
+ */
+export declare function loadOne<TStore extends StoreInterface>(parentStore: Store<TStore>, primaryKey: IDBValidKey): Promise<InferSelect<TStore> | null>;
+/** Alias of `loadMany` for readability at call sites. */
+export declare const findByForeignKey: typeof loadMany;

package/dist/relation/load-related.js

@@ -0,0 +1,54 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findByForeignKey = exports.loadOne = exports.loadMany = void 0;
+const errors_1 = require("../errors");
+/**
+ * Load many child rows by foreign key (`hasMany`).
+ *
+ * Explicit helper — not Prisma `include`. Prefer calling inside
+ * `transaction()` when loading parent + children together.
+ *
+ * **N+1:** calling this once per parent in a loop hits the index once per
+ * parent. For many parents, prefer one `findMany` + group in memory, or
+ * accept the N+1 cost for small sets.
+ */
+function loadMany(childStore, foreignKey, parentKey) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const field = childStore.def.fields[foreignKey];
+        if (!field) {
+            throw new errors_1.IndexedDbError('QUERY_INVALID', `loadMany: unknown field "${foreignKey}" on store "${childStore.name}"`, { store: childStore.name, field: foreignKey });
+        }
+        if (!field.meta.index && !field.meta.primaryKey) {
+            throw new errors_1.IndexedDbError('QUERY_INVALID', `loadMany: "${childStore.name}.${foreignKey}" must be indexed for FK lookup`, { store: childStore.name, field: foreignKey });
+        }
+        return childStore.findMany({
+            where: { [foreignKey]: parentKey },
+        });
+    });
+}
+exports.loadMany = loadMany;
+/**
+ * Load one parent row by primary key (`belongsTo`).
+ * Pass the FK value from the child row.
+ */
+function loadOne(parentStore, primaryKey) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const pk = parentStore.def.primaryKey.keyPath;
+        return parentStore.find({
+            where: { [pk]: primaryKey },
+        });
+    });
+}
+exports.loadOne = loadOne;
+/** Alias of `loadMany` for readability at call sites. */
+exports.findByForeignKey = loadMany;
+//# sourceMappingURL=load-related.js.map

package/dist/relation/load-related.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-related.js","sourceRoot":"","sources":["../../src/relation/load-related.ts"],"names":[],"mappings":";;;;;;;;;;;;AAGA,sCAA2C;AAE3C;;;;;;;;;GASG;AACH,SAAsB,QAAQ,CAC5B,UAAyB,EACzB,UAA2C,EAC3C,SAAsB;;QAEtB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAChD,IAAI,CAAC,KAAK,EAAE;YACV,MAAM,IAAI,uBAAc,CACtB,eAAe,EACf,4BAA4B,UAAU,eAAe,UAAU,CAAC,IAAI,GAAG,EACvE,EAAE,KAAK,EAAE,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,CAC9C,CAAC;SACH;QACD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE;YAC/C,MAAM,IAAI,uBAAc,CACtB,eAAe,EACf,cAAc,UAAU,CAAC,IAAI,IAAI,UAAU,iCAAiC,EAC5E,EAAE,KAAK,EAAE,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,CAC9C,CAAC;SACH;QACD,OAAO,UAAU,CAAC,QAAQ,CAAC;YACzB,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,SAAS,EAAW;SAC5C,CAAC,CAAC;IACL,CAAC;CAAA;AAvBD,4BAuBC;AAED;;;GAGG;AACH,SAAsB,OAAO,CAC3B,WAA0B,EAC1B,UAAuB;;QAEvB,MAAM,EAAE,GAAG,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC;QAC9C,OAAO,WAAW,CAAC,IAAI,CAAC;YACtB,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,UAAU,EAAW;SACrC,CAAC,CAAC;IACL,CAAC;CAAA;AARD,0BAQC;AAED,yDAAyD;AAC5C,QAAA,gBAAgB,GAAG,QAAQ,CAAC"}

package/dist/schema/define-db.d.ts

@@ -0,0 +1,5 @@
+import type { DbConfigInterface, DbStoresInterface, DeclaredDbInterface, DeclaredStoreInterface, StoreInterface } from './types';
+/** Normalize store defs into a serializable schema snapshot for migrations. */
+export declare function toDeclaredStoreSchema(store: StoreInterface): DeclaredStoreInterface;
+export declare function toDeclaredDbSchema<TStores extends DbStoresInterface>(config: DbConfigInterface<TStores>): DeclaredDbInterface;
+export type { DbConfigInterface };

package/dist/schema/define-db.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toDeclaredDbSchema = exports.toDeclaredStoreSchema = void 0;
+const errors_1 = require("../errors");
+const define_relation_1 = require("../relation/define-relation");
+/** Normalize store defs into a serializable schema snapshot for migrations. */
+function toDeclaredStoreSchema(store) {
+    return {
+        name: store.name,
+        primaryKey: Object.assign({}, store.primaryKey),
+        indexes: store.indexes.map((index) => (Object.assign({}, index))),
+    };
+}
+exports.toDeclaredStoreSchema = toDeclaredStoreSchema;
+function toDeclaredDbSchema(config) {
+    if (!config.name) {
+        throw new errors_1.IndexedDbError('SCHEMA_INVALID', 'Database name is required');
+    }
+    if (!Number.isInteger(config.version) || config.version < 1) {
+        throw new errors_1.IndexedDbError('SCHEMA_INVALID', 'Database version must be an integer >= 1');
+    }
+    const stores = Object.values(config.stores).map(toDeclaredStoreSchema);
+    if (stores.length === 0) {
+        throw new errors_1.IndexedDbError('SCHEMA_INVALID', 'At least one store is required');
+    }
+    const names = new Set();
+    for (const store of stores) {
+        if (names.has(store.name)) {
+            throw new errors_1.IndexedDbError('SCHEMA_INVALID', `Duplicate store name "${store.name}"`);
+        }
+        names.add(store.name);
+    }
+    (0, define_relation_1.assertAllRefsValid)(config.stores);
+    return {
+        name: config.name,
+        version: config.version,
+        stores,
+    };
+}
+exports.toDeclaredDbSchema = toDeclaredDbSchema;
+//# sourceMappingURL=define-db.js.map

package/dist/schema/define-db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-db.js","sourceRoot":"","sources":["../../src/schema/define-db.ts"],"names":[],"mappings":";;;AAOA,sCAA2C;AAC3C,iEAAiE;AAEjE,+EAA+E;AAC/E,SAAgB,qBAAqB,CACnC,KAAqB;IAErB,OAAO;QACL,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,UAAU,oBAAO,KAAK,CAAC,UAAU,CAAE;QACnC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,mBAAM,KAAK,EAAG,CAAC;KACtD,CAAC;AACJ,CAAC;AARD,sDAQC;AAED,SAAgB,kBAAkB,CAChC,MAAkC;IAElC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE;QAChB,MAAM,IAAI,uBAAc,CAAC,gBAAgB,EAAE,2BAA2B,CAAC,CAAC;KACzE;IACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,GAAG,CAAC,EAAE;QAC3D,MAAM,IAAI,uBAAc,CACtB,gBAAgB,EAChB,0CAA0C,CAC3C,CAAC;KACH;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;IACvE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE;QACvB,MAAM,IAAI,uBAAc,CAAC,gBAAgB,EAAE,gCAAgC,CAAC,CAAC;KAC9E;IACD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE;QAC1B,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE;YACzB,MAAM,IAAI,uBAAc,CACtB,gBAAgB,EAChB,yBAAyB,KAAK,CAAC,IAAI,GAAG,CACvC,CAAC;SACH;QACD,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;KACvB;IACD,IAAA,oCAAkB,EAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAClC,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM;KACP,CAAC;AACJ,CAAC;AAhCD,gDAgCC"}

package/dist/schema/define-store.d.ts

@@ -0,0 +1,17 @@
+import { type AnyField } from './fields';
+import type { CompoundIndexType, StoreFieldsInterface, StoreInterface } from './types';
+export type CompoundIndexInterface<TFieldNames extends readonly string[] = readonly string[]> = {
+    name: string;
+    fields: TFieldNames;
+    unique?: boolean;
+};
+/** Declare a compound (multi-property) index. */
+export declare function compoundIndex<const TFieldNames extends readonly string[]>(name: string, fields: TFieldNames, options?: {
+    unique?: boolean;
+}): CompoundIndexInterface<TFieldNames>;
+/**
+ * Define an object store schema. Only indexed fields become IDBIndex entries;
+ * all fields participate in TypeScript InferSelect / InferInsert / typed where.
+ */
+export declare function defineStore<TFields extends StoreFieldsInterface, const TCompounds extends readonly CompoundIndexType[] = readonly CompoundIndexType[]>(name: string, fields: TFields, indexes?: (fields: TFields) => TCompounds): StoreInterface<TFields, TCompounds>;
+export type { AnyField };

package/dist/schema/define-store.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineStore = exports.compoundIndex = void 0;
+const fields_1 = require("./fields");
+const errors_1 = require("../errors");
+/** Declare a compound (multi-property) index. */
+function compoundIndex(name, fields, options) {
+    return { name, fields, unique: options === null || options === void 0 ? void 0 : options.unique };
+}
+exports.compoundIndex = compoundIndex;
+function resolvePrimaryKey(fields) {
+    const entries = Object.entries(fields).filter(([, fieldDef]) => fieldDef.meta.primaryKey);
+    if (entries.length === 0) {
+        throw new errors_1.IndexedDbError('SCHEMA_INVALID', 'Store must declare exactly one primaryKey() field');
+    }
+    if (entries.length > 1) {
+        throw new errors_1.IndexedDbError('SCHEMA_INVALID', 'Store must declare only one primaryKey() field');
+    }
+    const [keyPath, fieldDef] = entries[0];
+    return {
+        keyPath,
+        autoIncrement: fieldDef.meta.autoIncrement,
+    };
+}
+function collectIndexes(fields, extra = []) {
+    const indexes = [];
+    const names = new Set();
+    for (const [fieldName, fieldDef] of Object.entries(fields)) {
+        const spec = (0, fields_1.fieldIndexSpec)(fieldName, fieldDef);
+        if (!spec) {
+            continue;
+        }
+        if (names.has(spec.name)) {
+            throw new errors_1.IndexedDbError('SCHEMA_INVALID', `Duplicate index name "${spec.name}"`);
+        }
+        names.add(spec.name);
+        indexes.push(spec);
+    }
+    for (const compound of extra) {
+        if (names.has(compound.name)) {
+            throw new errors_1.IndexedDbError('SCHEMA_INVALID', `Duplicate index name "${compound.name}"`);
+        }
+        for (const fieldName of compound.fields) {
+            if (!(fieldName in fields) || !(0, fields_1.isField)(fields[fieldName])) {
+                throw new errors_1.IndexedDbError('SCHEMA_INVALID', `Compound index "${compound.name}" references unknown field "${fieldName}"`);
+            }
+        }
+        names.add(compound.name);
+        indexes.push({
+            name: compound.name,
+            keyPath: [...compound.fields],
+            unique: compound.unique,
+            multiEntry: false,
+        });
+    }
+    return indexes;
+}
+/**
+ * Define an object store schema. Only indexed fields become IDBIndex entries;
+ * all fields participate in TypeScript InferSelect / InferInsert / typed where.
+ */
+function defineStore(name, fields, indexes) {
+    if (!name) {
+        throw new errors_1.IndexedDbError('SCHEMA_INVALID', 'Store name is required');
+    }
+    for (const [key, value] of Object.entries(fields)) {
+        if (!(0, fields_1.isField)(value)) {
+            throw new errors_1.IndexedDbError('SCHEMA_INVALID', `Store "${name}" field "${key}" must be created with field.* builders`);
+        }
+    }
+    const primaryKey = resolvePrimaryKey(fields);
+    const extra = (indexes ? indexes(fields) : []);
+    const indexList = collectIndexes(fields, [...extra]);
+    const store = {
+        name,
+        fields,
+        primaryKey,
+        indexes: indexList,
+    };
+    for (const [fieldName, fieldDef] of Object.entries(fields)) {
+        if (!fieldDef.meta.ref) {
+            continue;
+        }
+        const indexed = fieldDef.meta.primaryKey ||
+            Boolean(fieldDef.meta.index) ||
+            indexList.some((i) => i.name === fieldName ||
+                (typeof i.keyPath === 'string' && i.keyPath === fieldName));
+        if (!indexed) {
+            throw new errors_1.IndexedDbError('SCHEMA_INVALID', `Store "${name}" field "${fieldName}" has .ref("${fieldDef.meta.ref.store}") but is not indexed. Chain .index() / .uniqueIndex() so FK lookups use an IDB index.`, { store: name, field: fieldName });
+        }
+    }
+    return store;
+}
+exports.defineStore = defineStore;
+//# sourceMappingURL=define-store.js.map

package/dist/schema/define-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-store.js","sourceRoot":"","sources":["../../src/schema/define-store.ts"],"names":[],"mappings":";;;AAAA,qCAAkE;AAQlE,sCAA2C;AAU3C,iDAAiD;AACjD,SAAgB,aAAa,CAC3B,IAAY,EACZ,MAAmB,EACnB,OAA8B;IAE9B,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM,EAAE,CAAC;AACnD,CAAC;AAND,sCAMC;AAED,SAAS,iBAAiB,CAAC,MAA4B;IACrD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CAC3C,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAC3C,CAAC;IACF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE;QACxB,MAAM,IAAI,uBAAc,CACtB,gBAAgB,EAChB,mDAAmD,CACpD,CAAC;KACH;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE;QACtB,MAAM,IAAI,uBAAc,CACtB,gBAAgB,EAChB,gDAAgD,CACjD,CAAC;KACH;IACD,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACvC,OAAO;QACL,OAAO;QACP,aAAa,EAAE,QAAQ,CAAC,IAAI,CAAC,aAAa;KAC3C,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CACrB,MAA4B,EAC5B,QAA6B,EAAE;IAE/B,MAAM,OAAO,GAAqB,EAAE,CAAC;IACrC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAEhC,KAAK,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE;QAC1D,MAAM,IAAI,GAAG,IAAA,uBAAc,EAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI,EAAE;YACT,SAAS;SACV;QACD,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;YACxB,MAAM,IAAI,uBAAc,CACtB,gBAAgB,EAChB,yBAAyB,IAAI,CAAC,IAAI,GAAG,CACtC,CAAC;SACH;QACD,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;KACpB;IAED,KAAK,MAAM,QAAQ,IAAI,KAAK,EAAE;QAC5B,IAAI,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE;YAC5B,MAAM,IAAI,uBAAc,CACtB,gBAAgB,EAChB,yBAAyB,QAAQ,CAAC,IAAI,GAAG,CAC1C,CAAC;SACH;QACD,KAAK,MAAM,SAAS,IAAI,QAAQ,CAAC,MAAM,EAAE;YACvC,IAAI,CAAC,CAAC,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,IAAA,gBAAO,EAAC,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE;gBACzD,MAAM,IAAI,uBAAc,CACtB,gBAAgB,EAChB,mBAAmB,QAAQ,CAAC,IAAI,+BAA+B,SAAS,GAAG,CAC5E,CAAC;aACH;SACF;QACD,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACzB,OAAO,CAAC,IAAI,CAAC;YACX,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,OAAO,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC;YAC7B,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,UAAU,EAAE,KAAK;SAClB,CAAC,CAAC;KACJ;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,SAAgB,WAAW,CAIzB,IAAY,EACZ,MAAe,EACf,OAAyC;IAEzC,IAAI,CAAC,IAAI,EAAE;QACT,MAAM,IAAI,uBAAc,CAAC,gBAAgB,EAAE,wBAAwB,CAAC,CAAC;KACtE;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE;QACjD,IAAI,CAAC,IAAA,gBAAO,EAAC,KAAK,CAAC,EAAE;YACnB,MAAM,IAAI,uBAAc,CACtB,gBAAgB,EAChB,UAAU,IAAI,YAAY,GAAG,yCAAyC,CACvE,CAAC;SACH;KACF;IAED,MAAM,UAAU,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAe,CAAC;IAC7D,MAAM,SAAS,GAAG,cAAc,CAAC,MAAM,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;IAErD,MAAM,KAAK,GAAwC;QACjD,IAAI;QACJ,MAAM;QACN,UAAU;QACV,OAAO,EAAE,SAAS;KACnB,CAAC;IAEF,KAAK,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE;QAC1D,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE;YACtB,SAAS;SACV;QACD,MAAM,OAAO,GACX,QAAQ,CAAC,IAAI,CAAC,UAAU;YACxB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC;YAC5B,SAAS,CAAC,IAAI,CACZ,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,IAAI,KAAK,SAAS;gBACpB,CAAC,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO,KAAK,SAAS,CAAC,CAC7D,CAAC;QACJ,IAAI,CAAC,OAAO,EAAE;YACZ,MAAM,IAAI,uBAAc,CACtB,gBAAgB,EAChB,UAAU,IAAI,YAAY,SAAS,eAAe,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,wFAAwF,EACjK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAClC,CAAC;SACH;KACF;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AArDD,kCAqDC"}