@zmdb/schema 1.0.0-beta.1

package/dist/dto/index.js

@@ -0,0 +1,118 @@
+import {} from '../derive/index.js';
+import {} from '../index.js';
+function base64Encode(str) {
+    if (globalThis.Buffer) {
+        return globalThis.Buffer.from(str, 'utf-8').toString('base64url');
+    }
+    if (globalThis.btoa) {
+        return globalThis.btoa(str).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+    }
+    throw new Error('No base64 encoder available');
+}
+function base64Decode(str) {
+    if (globalThis.Buffer) {
+        return globalThis.Buffer.from(str, 'base64url').toString('utf-8');
+    }
+    if (globalThis.atob) {
+        let base64 = str.replace(/-/g, '+').replace(/_/g, '/');
+        while (base64.length % 4)
+            base64 += '=';
+        return globalThis.atob(base64);
+    }
+    throw new Error('No base64 decoder available');
+}
+export function encodeCursor(payload) {
+    return base64Encode(JSON.stringify(payload));
+}
+export function decodeCursor(cursor) {
+    if (typeof cursor !== 'string' || !cursor.trim()) {
+        throw new Error('Invalid cursor: must be a non-empty string');
+    }
+    try {
+        const json = base64Decode(cursor);
+        const parsed = JSON.parse(json);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            throw new Error('Invalid cursor payload');
+        }
+        // boundary: JSON.parse returns unknown (untrusted client payload); runtime check above proves parsed is a non-null, non-array object.
+        return parsed;
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.startsWith('Invalid cursor')) {
+            throw err;
+        }
+        throw new Error(`Invalid cursor format: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+}
+export function project(row, cols) {
+    if (!cols)
+        return row;
+    // boundary: a `Pick` is built key-by-key, so it is only complete once the loop
+    // ends — there is no expression form that types a partially-filled mapped
+    // type. The loop below writes exactly `cols`, which is what `Pick<Row, K>`
+    // claims; `noUncheckedIndexedAccess` keeps the reads honest.
+    const out = {};
+    for (const c of cols)
+        out[c] = row[c];
+    return out;
+}
+/** Apply a Get's select projection to a fetched row. */
+export function getResult(row, opts) {
+    return project(row, opts?.select);
+}
+export function buildListResult(rows, opts) {
+    const limit = opts?.limit;
+    const hasMore = typeof limit === 'number' && rows.length > limit;
+    const kept = hasMore ? rows.slice(0, limit) : rows;
+    const select = opts?.select;
+    const items = select ? kept.map(r => project(r, select)) : kept;
+    let computedCursor = opts?.cursor;
+    if (!computedCursor && hasMore && kept.length > 0) {
+        const lastRow = kept[kept.length - 1];
+        if (lastRow) {
+            const cursorObj = {};
+            const cols = opts?.orderBy ? [...opts.orderBy] : [];
+            if (opts?.pkColumn && !cols.some(c => String(c.column) === opts.pkColumn)) {
+                cols.push({ column: opts.pkColumn, dir: 'asc' });
+            }
+            for (const item of cols) {
+                if (!item)
+                    continue;
+                const colStr = String(item.column);
+                if (colStr in lastRow) {
+                    cursorObj[colStr] = lastRow[colStr];
+                }
+            }
+            if (Object.keys(cursorObj).length > 0) {
+                computedCursor = encodeCursor(cursorObj);
+            }
+        }
+    }
+    const result = {
+        items,
+        hasMore,
+        ...(computedCursor !== undefined ? { cursor: computedCursor } : {}),
+    };
+    return opts?.total !== undefined ? { ...result, total: opts.total } : result;
+}
+/** Ordered field list for an aggregate spec: group-key cols then computed keys. */
+export function describeAggregate(spec) {
+    const keys = (spec.groupBy ?? []).map(k => String(k));
+    return [...keys, ...Object.keys(spec.computed)];
+}
+/** Assemble a SearchResult (reuses buildListResult; preserves _score on hits). */
+export function buildSearchResult(rows, opts) {
+    const limit = opts?.limit;
+    const hasMore = typeof limit === 'number' && rows.length > limit;
+    const kept = hasMore ? rows.slice(0, limit) : rows;
+    const items = kept.map(hit => {
+        // `SearchHit<Row>` is `Row & {_score?}`, so it *is* a `Row` for projection
+        // purposes — no `hit as Row` needed once `project` is keyed on the argument.
+        const base = opts?.select ? project(hit, opts.select) : hit;
+        // preserve the ranking score on the projected hit
+        return hit._score !== undefined ? { ...base, _score: hit._score } : base;
+    });
+    const result = { items, hasMore };
+    return opts?.total !== undefined ? { ...result, total: opts.total } : result;
+}
+//# sourceMappingURL=index.js.map

package/dist/dto/index.js.map

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

package/dist/entity-modeling/index.d.ts

@@ -0,0 +1,12 @@
+export declare function flattenEmbeddable(prefix: string, value: Record<string, unknown>): Record<string, unknown>;
+export declare function liftEmbeddable(prefix: string, row: Record<string, unknown>): Record<string, unknown>;
+export interface SingleTableInheritance {
+    discriminator: string;
+    map: Record<string, readonly string[]>;
+}
+export declare function discriminatorFor(_sti: SingleTableInheritance, type: string): string;
+export declare function rowToSubtype(sti: SingleTableInheritance, row: Record<string, unknown>): {
+    type: string;
+    data: Record<string, unknown>;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/entity-modeling/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/entity-modeling/index.ts"],"names":[],"mappings":"AACA,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIzG;AACD,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOpG;AAGD,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;CACxC;AACD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,sBAAsB,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnF;AACD,wBAAgB,YAAY,CAC1B,GAAG,EAAE,sBAAsB,EAC3B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAMjD"}

package/dist/entity-modeling/index.js

@@ -0,0 +1,28 @@
+// §2 embeddables
+export function flattenEmbeddable(prefix, value) {
+    const out = {};
+    for (const [k, v] of Object.entries(value))
+        out[`${prefix}_${k}`] = v;
+    return out;
+}
+export function liftEmbeddable(prefix, row) {
+    const p = `${prefix}_`;
+    const out = {};
+    for (const [k, v] of Object.entries(row)) {
+        if (k.startsWith(p))
+            out[k.slice(p.length)] = v;
+    }
+    return out;
+}
+export function discriminatorFor(_sti, type) {
+    return type;
+}
+export function rowToSubtype(sti, row) {
+    const type = String(row[sti.discriminator]);
+    const cols = sti.map[type] ?? [];
+    const data = {};
+    for (const c of cols)
+        data[c] = row[c];
+    return { type, data };
+}
+//# sourceMappingURL=index.js.map

package/dist/entity-modeling/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/entity-modeling/index.ts"],"names":[],"mappings":"AAAA,iBAAiB;AACjB,MAAM,UAAU,iBAAiB,CAAC,MAAc,EAAE,KAA8B;IAC9E,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,GAAG,CAAC,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IACtE,OAAO,GAAG,CAAC;AACb,CAAC;AACD,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,GAA4B;IACzE,MAAM,CAAC,GAAG,GAAG,MAAM,GAAG,CAAC;IACvB,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACzC,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;YAAE,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAOD,MAAM,UAAU,gBAAgB,CAAC,IAA4B,EAAE,IAAY;IACzE,OAAO,IAAI,CAAC;AACd,CAAC;AACD,MAAM,UAAU,YAAY,CAC1B,GAA2B,EAC3B,GAA4B;IAE5B,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IACjC,MAAM,IAAI,GAA4B,EAAE,CAAC;IACzC,KAAK,MAAM,CAAC,IAAI,IAAI;QAAE,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;IACvC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACxB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,151 @@
+import { type ExtensionType, type SchemaIR } from './ir/index.js';
+export type SqlType = 'serial' | 'integer' | 'bigint' | 'numeric' | 'text' | 'varchar' | 'boolean' | 'timestamp' | 'json' | 'jsonEnum';
+export interface ValidationRule {
+    readonly kind: string;
+    readonly value?: unknown;
+    readonly message?: string;
+    /**
+     * The argument list, for a rule that came from `@zmdb/validator`'s runtime `tags`.
+     *
+     * Declared rather than tolerated: `ir/index.ts`'s `ruleArgument` has always read it,
+     * and `openapi.spec.ts` has always passed one, so leaving it off the type meant the
+     * only two writers of this field disagreed with its declaration.
+     */
+    readonly args?: readonly unknown[];
+}
+export interface ColumnFlags {
+    readonly nullable: boolean;
+    readonly primaryKey?: boolean | undefined;
+    readonly unique?: boolean | undefined;
+    readonly autoIncrement?: boolean | undefined;
+    readonly hasDefault?: boolean | undefined;
+    readonly length?: number | undefined;
+    readonly enum?: readonly string[] | undefined;
+    readonly sensitive?: boolean | undefined;
+}
+export interface ColumnMeta {
+    readonly type: SqlType | ExtensionType;
+    readonly flags: ColumnFlags;
+    readonly default?: unknown;
+    readonly references?: {
+        readonly target: string;
+    };
+    readonly validation?: readonly ValidationRule[];
+}
+export type ColumnsMap = Readonly<Record<string, ColumnMeta>>;
+/**
+ * A schema value: a table described in physical SQL names, for the code that runs.
+ *
+ * There is no type parameter for the column map, and its absence is the point. It used to
+ * carry the *literal* map so that `Entity<S>` could read property types out of it; every
+ * derivation now takes the declared type instead, so a literal map would be a parameter
+ * nothing reads. `table`, `columns`, `primaryKey` and the local side of `references` are
+ * in database vocabulary. The carried IR keeps declared names for derived types,
+ * validation, payloads and result aliases.
+ */
+export interface CoreSchema<T extends string = string> {
+    readonly table: T;
+    readonly columns: ColumnsMap;
+    readonly primaryKey: readonly string[];
+    readonly references: readonly {
+        readonly column: string;
+        readonly target: string;
+    }[];
+    readonly ftsTable?: string | boolean | undefined;
+    /**
+     * The IR this value was built from, carried rather than recomputed.
+     *
+     * Required, and that is the point. `columns` is a lossy projection: a `ColumnMeta` has
+     * a `SqlType` and a flag map, and it has nowhere to put a json payload's shape, a
+     * constraint's arguments, or the difference between a column that is `integer + Serial`
+     * and one that is merely `integer`. There used to be an `irFromSchema` that guessed
+     * those back — four walkers over column metadata, each reconstructing what the
+     * declaration had already said, each with its own idea of the answer. Every one of them
+     * now reads this field, so the DDL, the validator, the JSON Schema and the seeder are
+     * looking at the same bytes.
+     *
+     * `schemaFromIR(schema.ir)` is `schema` (see `ir.spec.ts`), which is what makes the
+     * field safe to depend on: it holds everything the value does, so nothing has to choose
+     * between them.
+     */
+    readonly ir: SchemaIR;
+}
+declare const zmdbEntity: unique symbol;
+/**
+ * A schema value that remembers the type it was generated from.
+ *
+ * The query compiler wants the table and the column types as data, so a tagged
+ * declaration still has to become a `CoreSchema` — but a `CoreSchema` has erased which
+ * type it came from, and a column map cannot be read back into one: it has a `SqlType`
+ * and a flag bag, and nowhere to put a json payload's shape. This phantom keeps the
+ * answer instead of reconstructing it. `schemaOf<User>()` is a `TaggedSchema<User>`, so
+ * anything holding the value can recover `User` and derive from the declaration.
+ *
+ * The slot is a `unique symbol` like every tag in `./tags`, and for the same reason:
+ * un-forgeable, and it erases, so no generated literal carries it at runtime. It is
+ * *required* rather than optional, which is what makes it inferrable: a function that
+ * wants the declared type asks for a `TaggedSchema<T>` and gets `T` from the argument,
+ * which is how `defineRepository`, `defineEntityStateMachine` and `findJoined` are
+ * parameterised on a declaration while still being handed a value.
+ */
+export interface TaggedSchema<T> extends CoreSchema<string> {
+    readonly [zmdbEntity]: T;
+}
+/**
+ * The schema value for a tagged type, generated at build time.
+ *
+ * The only way to get one, and it declares nothing: `User` already says the table, the
+ * columns, the keys and the constraints, so this asks for that declaration as data.
+ * `@zmdb/compiler` replaces the call with a frozen literal — `schemaFromIR` applied
+ * to the IR it read off `T` — so the schema is written exactly once, in the type.
+ *
+ * ```ts
+ * const users = defineRepository(schemaOf<User>(), driver);
+ * ```
+ *
+ * There is no runtime implementation and cannot be one, for the same reason
+ * `toJsonSchema<T>()` has none: the answer is a function of a type argument, and type
+ * arguments do not survive to runtime. A build that did not run the transform gets an
+ * error saying so rather than a plausible-looking empty schema.
+ */
+export declare function schemaOf<T>(): TaggedSchema<T>;
+export { type CreateDTO, type DeclaredTable, type Entity, type PrimaryKeyOf, type ReadDTO, type UpdateDTO, } from './derive/index.js';
+/**
+ * True for a non-null, non-array object.
+ *
+ * Lives here (the DAG root) because every downstream package needs the same
+ * proof before a keyed read: without it, reading `value[key]` off an `unknown`
+ * requires `as Record<string, unknown>`, and those casts are exactly what
+ * ARCHITECTURE §2.1 forbids on the public surface.
+ */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Invariant type equality. Stricter than mutual assignability: it distinguishes
+ * `any`/`unknown`/`never` and does not collapse optional vs `| undefined`.
+ */
+export type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => (T extends B ? 1 : 2) ? true : false;
+/** One-way assignability, for "at least this shape" assertions. */
+export type Extends<A, B> = [A] extends [B] ? true : false;
+/**
+ * Two-way assignability: each side accepts the other, differences in intersection
+ * spelling and union ordering included.
+ *
+ * This is the right tool for asserting what a derived type *means* when the columns
+ * are tagged. `Entity<User>['email']` is `string & Sql<'text'>`, not `string`, because
+ * a tag survives every derivation on purpose (that is how a projection or an aggregate
+ * still knows the column's SQL type). `Equal` sees two different types there and is
+ * correct to; `Mutual` sees that either can be used where the other is expected, which
+ * is the claim such a test is usually making. Pair it with `Equal<keyof A, keyof B>`
+ * when the key set and optionality matter too — assignability alone does not pin those.
+ */
+export type Mutual<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+/** Assert a type-level predicate. `Expect<Equal<X, Y>>` fails to compile if X ≠ Y. */
+export type Expect<T extends true> = T;
+/** Negative form: `ExpectNot<Equal<X, Y>>` fails to compile if X = Y. */
+export type ExpectNot<T extends false> = T;
+export { resolveRelation } from './relations/index.js';
+export { type ResolvedRelation } from './relations/index.js';
+export { type Populated, type PopulatedEntity } from './derive/index.js';
+export { type WhereDTO, type ListDTO, type ListResult, type OrderByDTO, type PaginationDTO } from './dto/index.js';
+export { buildListResult } from './dto/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,84 @@
+// @zmdb/schema — the vocabulary a table is described in, and the derivations
+// every other package reads off it.
+//
+// There is no builder DSL any more — `defineSchema`, the ten column builders and the
+// eight function-style modifiers were deleted with the last of their callers, and
+// `schemaOf<T>()` is what produces a schema value now. A table is declared once, as a
+// type, in the tags of `./tags`; `@zmdb/compiler` reflects that declaration into a
+// `SchemaIR` and `schemaFromIR` turns the IR into the value the query compiler reads. So
+// what is left in this file is the *data model* — `SqlType`, `ColumnFlags`, `ColumnMeta`,
+// `CoreSchema` — plus the derived-type family and the type-level assertion helpers.
+//
+// The derived types have one spelling each, and it takes the declared type. See the
+// DTO suite below.
+// The IR bindings below are types. With verbatimModuleSyntax, the named import
+// clause remains an empty runtime import of the IR module.
+import {} from './ir/index.js';
+/**
+ * The schema value for a tagged type, generated at build time.
+ *
+ * The only way to get one, and it declares nothing: `User` already says the table, the
+ * columns, the keys and the constraints, so this asks for that declaration as data.
+ * `@zmdb/compiler` replaces the call with a frozen literal — `schemaFromIR` applied
+ * to the IR it read off `T` — so the schema is written exactly once, in the type.
+ *
+ * ```ts
+ * const users = defineRepository(schemaOf<User>(), driver);
+ * ```
+ *
+ * There is no runtime implementation and cannot be one, for the same reason
+ * `toJsonSchema<T>()` has none: the answer is a function of a type argument, and type
+ * arguments do not survive to runtime. A build that did not run the transform gets an
+ * error saying so rather than a plausible-looking empty schema.
+ */
+export function schemaOf() {
+    throw new Error('schemaOf<T>() was not replaced at build time. It is compiled away by @zmdb/compiler ' +
+        '(the unplugin, Metro adapter, or project compiler), which did not run over this file — a type argument cannot ' +
+        'be read at runtime, so there is nothing to fall back to.');
+}
+// ---------------------------------------------------------------------------
+// The DTO suite (REQ-TF-4)
+// ---------------------------------------------------------------------------
+//
+// Re-exported, not defined. `./derive` reads the declared type, and there is no second
+// spelling any more: each of these used to have a column-map twin here, with every
+// derivation choosing between them by asking `S extends TaggedSchema<infer T>`.
+//
+// Both halves of that had to go. The column-map walk could not answer some of the
+// questions — a `json` column came out `unknown`, because a payload's shape is a type
+// and a `ColumnMeta` has nowhere to put one — so the two branches did not merely differ
+// in spelling, they differed in what they knew. And the dispatch meant every derivation
+// asked a question about its argument before it could begin, which is the inversion this
+// design exists to remove: the declaration is the source, and a value generated from it
+// is downstream.
+//
+// What takes the place of the dispatch is inference, once, at the boundary where a value
+// actually arrives: a function that is handed a generated schema declares the parameter
+// `TaggedSchema<T>` and gets `T` from it (`defineRepository`, `findJoined`,
+// `defineEntityStateMachine`, `repositoryToken`). Everything after that point is
+// parameterised on the declared type. `schema-of.type-test.ts` pins the crossing.
+export {} from './derive/index.js';
+/**
+ * True for a non-null, non-array object.
+ *
+ * Lives here (the DAG root) because every downstream package needs the same
+ * proof before a keyed read: without it, reading `value[key]` off an `unknown`
+ * requires `as Record<string, unknown>`, and those casts are exactly what
+ * ARCHITECTURE §2.1 forbids on the public surface.
+ */
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// Relations: resolution and the two row helpers. `Populated`/`PopulatedEntity` come from
+// `./derive`, which reads the relation off the declared type — there is no relations map to
+// derive them from any more, and no `manyToOne`/`oneToMany`/`oneToOne`/`manyToMany` builder
+// to write one with.
+export { resolveRelation } from './relations/index.js';
+export {} from './relations/index.js';
+export {} from './derive/index.js';
+// ---------------------------------------------------------------------------
+// Entity State Machine & State Transition Helpers
+// ---------------------------------------------------------------------------
+export {} from './dto/index.js';
+export { buildListResult } from './dto/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,oCAAoC;AACpC,EAAE;AACF,qFAAqF;AACrF,kFAAkF;AAClF,sFAAsF;AACtF,mFAAmF;AACnF,yFAAyF;AACzF,0FAA0F;AAC1F,oFAAoF;AACpF,EAAE;AACF,oFAAoF;AACpF,mBAAmB;AAEnB,+EAA+E;AAC/E,2DAA2D;AAC3D,OAAO,EAAqC,MAAM,eAAe,CAAC;AA0HlE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,QAAQ;IACtB,MAAM,IAAI,KAAK,CACb,sFAAsF;QACpF,gHAAgH;QAChH,0DAA0D,CAC7D,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAC9E,EAAE;AACF,uFAAuF;AACvF,mFAAmF;AACnF,gFAAgF;AAChF,EAAE;AACF,kFAAkF;AAClF,sFAAsF;AACtF,wFAAwF;AACxF,wFAAwF;AACxF,yFAAyF;AACzF,wFAAwF;AACxF,iBAAiB;AACjB,EAAE;AACF,yFAAyF;AACzF,wFAAwF;AACxF,4EAA4E;AAC5E,iFAAiF;AACjF,kFAAkF;AAClF,OAAO,EAON,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AA8CD,yFAAyF;AACzF,4FAA4F;AAC5F,4FAA4F;AAC5F,qBAAqB;AACrB,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAyB,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAwC,MAAM,mBAAmB,CAAC;AAEzE,8EAA8E;AAC9E,kDAAkD;AAClD,8EAA8E;AAE9E,OAAO,EAAqF,MAAM,gBAAgB,CAAC;AACnH,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}