genjutsu-db 0.1.0

package/dist/migrations.js

@@ -0,0 +1,163 @@
+/**
+ * Migration runner for the genjutsu-db library.
+ * Versioned up() migrations with tracking in _genjutsu_migrations sheet.
+ */
+import { getSpreadsheetMetadata, structuralBatchUpdate, getSheetValues, updateSheet, } from "./transport";
+import { schemaError, migrationError } from "./errors";
+const MIGRATIONS_SHEET = "_genjutsu_migrations";
+const MIGRATIONS_RANGE = `${MIGRATIONS_SHEET}!A2:C`;
+/**
+ * Run pending migrations, tracking applied ones in _genjutsu_migrations.
+ */
+export async function runMigrations(ctx, migrations) {
+    // Validate: no duplicate version numbers
+    const versions = new Set();
+    for (const m of migrations) {
+        if (versions.has(m.version)) {
+            throw schemaError(`Migrations have duplicate version number: ${m.version}`);
+        }
+        versions.add(m.version);
+    }
+    // Sort migrations by version ascending
+    const sorted = [...migrations].sort((a, b) => a.version - b.version);
+    // Ensure _genjutsu_migrations sheet exists
+    const metadata = await getSpreadsheetMetadata(ctx);
+    const sheetIdMap = new Map();
+    for (const s of metadata.sheets) {
+        sheetIdMap.set(s.title, s.sheetId);
+    }
+    if (!sheetIdMap.has(MIGRATIONS_SHEET)) {
+        await structuralBatchUpdate(ctx, [
+            { addSheet: { properties: { title: MIGRATIONS_SHEET } } },
+        ]);
+        // Refresh metadata after creating the sheet
+        const refreshed = await getSpreadsheetMetadata(ctx);
+        for (const s of refreshed.sheets) {
+            sheetIdMap.set(s.title, s.sheetId);
+        }
+    }
+    // Read applied migration versions
+    const rows = await getSheetValues(ctx, MIGRATIONS_RANGE, "UNFORMATTED_VALUE");
+    const appliedVersions = new Set();
+    for (const row of rows) {
+        const ver = Number(row[0]);
+        if (!Number.isNaN(ver))
+            appliedVersions.add(ver);
+    }
+    // Filter to pending migrations
+    const pending = sorted.filter((m) => !appliedVersions.has(m.version));
+    if (pending.length === 0)
+        return;
+    // Create migration context
+    const mCtx = createMigrationContext(ctx, sheetIdMap);
+    // Execute each pending migration
+    for (const m of pending) {
+        try {
+            await m.up(mCtx);
+        }
+        catch (err) {
+            throw migrationError(`Migration ${m.version} (${m.name}) failed: ${err instanceof Error ? err.message : String(err)}`, m.version, m.name, err);
+        }
+        // Record the successful migration
+        const timestamp = new Date().toISOString();
+        await updateSheet(ctx, `${MIGRATIONS_SHEET}!A1:C`, [[m.version, m.name, timestamp]], true);
+    }
+}
+/**
+ * Create a MigrationContext that wraps the transport context.
+ */
+function createMigrationContext(ctx, sheetIdMap) {
+    function resolveSheetId(sheetName) {
+        const id = sheetIdMap.get(sheetName);
+        if (id === undefined) {
+            throw schemaError(`Sheet "${sheetName}" not found in spreadsheet`);
+        }
+        return id;
+    }
+    return {
+        async createSheet(name) {
+            await structuralBatchUpdate(ctx, [
+                { addSheet: { properties: { title: name } } },
+            ]);
+        },
+        async addColumn(sheet, column, afterIndex) {
+            const sheetId = resolveSheetId(sheet);
+            const colIndex = afterIndex ?? 0;
+            await structuralBatchUpdate(ctx, [
+                {
+                    insertDimension: {
+                        range: {
+                            sheetId,
+                            dimension: "COLUMNS",
+                            startIndex: colIndex,
+                            endIndex: colIndex + 1,
+                        },
+                        inheritFromBefore: false,
+                    },
+                },
+                {
+                    updateCells: {
+                        rows: [
+                            {
+                                values: [
+                                    {
+                                        userEnteredValue: { stringValue: column },
+                                    },
+                                ],
+                            },
+                        ],
+                        start: { sheetId, rowIndex: 0, columnIndex: colIndex },
+                        fields: "userEnteredValue",
+                    },
+                },
+            ]);
+        },
+        async removeColumn(sheet, columnIndex) {
+            const sheetId = resolveSheetId(sheet);
+            await structuralBatchUpdate(ctx, [
+                {
+                    deleteDimension: {
+                        range: {
+                            sheetId,
+                            dimension: "COLUMNS",
+                            startIndex: columnIndex,
+                            endIndex: columnIndex + 1,
+                        },
+                    },
+                },
+            ]);
+        },
+        async renameColumn(sheet, columnIndex, newName) {
+            const sheetId = resolveSheetId(sheet);
+            await structuralBatchUpdate(ctx, [
+                {
+                    updateCells: {
+                        rows: [
+                            {
+                                values: [
+                                    {
+                                        userEnteredValue: { stringValue: newName },
+                                    },
+                                ],
+                            },
+                        ],
+                        start: { sheetId, rowIndex: 0, columnIndex },
+                        fields: "userEnteredValue",
+                    },
+                },
+            ]);
+        },
+        async renameSheet(oldName, newName) {
+            const sheetId = resolveSheetId(oldName);
+            await structuralBatchUpdate(ctx, [
+                {
+                    updateSheetProperties: {
+                        properties: { sheetId, title: newName },
+                        fields: "title",
+                    },
+                },
+            ]);
+        },
+    };
+}
+//# sourceMappingURL=migrations.js.map

package/dist/migrations.js.map

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

package/dist/model.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Model definition API for the genjutsu-db library.
+ * Provides field builders and defineModel() for TypeScript-first schema definition.
+ */
+import type { SheetSchema } from "./types";
+export interface FieldDef<T = unknown> {
+    readonly _type: "string" | "number" | "date" | "boolean";
+    readonly _isPrimaryKey: boolean;
+    readonly _isOptional: boolean;
+    readonly _defaultValue: T | undefined;
+    readonly _references: {
+        model: string;
+        field: string;
+    } | undefined;
+    primaryKey(): FieldDef<T>;
+    optional(): FieldDef<T | null>;
+    default(value: T): FieldDef<T>;
+    references(model: string, field: string): FieldDef<T>;
+}
+export declare const field: {
+    string: () => FieldDef<string>;
+    number: () => FieldDef<number>;
+    date: () => FieldDef<string>;
+    boolean: () => FieldDef<boolean>;
+};
+export declare function defineModel<F extends Record<string, FieldDef<any>>>(sheetName: string, fields: F): SheetSchema<any>;
+//# sourceMappingURL=model.d.ts.map

package/dist/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAuC,MAAM,SAAS,CAAC;AAOhF,MAAM,WAAW,QAAQ,CAAC,CAAC,GAAG,OAAO;IACnC,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;IACzD,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,CAAC,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,WAAW,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IACnE,UAAU,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC1B,QAAQ,IAAI,QAAQ,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC/B,OAAO,CAAC,KAAK,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC/B,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;CACvD;AA8BD,eAAO,MAAM,KAAK;;;;;CAKjB,CAAC;AAWF,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,EACjE,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,CAAC,GACR,WAAW,CAAC,GAAG,CAAC,CAsHlB"}

package/dist/model.js

@@ -0,0 +1,138 @@
+/**
+ * Model definition API for the genjutsu-db library.
+ * Provides field builders and defineModel() for TypeScript-first schema definition.
+ */
+import { schemaError, validationError } from "./errors";
+function createFieldDef(type, isPrimaryKey = false, isOptional = false, defaultValue = undefined, references = undefined) {
+    return {
+        _type: type,
+        _isPrimaryKey: isPrimaryKey,
+        _isOptional: isOptional,
+        _defaultValue: defaultValue,
+        _references: references,
+        primaryKey() {
+            return createFieldDef(type, true, isOptional, defaultValue, references);
+        },
+        optional() {
+            return createFieldDef(type, isPrimaryKey, true, defaultValue, references);
+        },
+        default(value) {
+            return createFieldDef(type, isPrimaryKey, isOptional, value, references);
+        },
+        references(model, field) {
+            return createFieldDef(type, isPrimaryKey, isOptional, defaultValue, { model, field });
+        },
+    };
+}
+export const field = {
+    string: () => createFieldDef("string"),
+    number: () => createFieldDef("number"),
+    date: () => createFieldDef("date"),
+    boolean: () => createFieldDef("boolean"),
+};
+// ---------------------------------------------------------------------------
+// defineModel — generates SheetSchema from field declarations
+// ---------------------------------------------------------------------------
+function columnLetter(index) {
+    // 0-based index to A-Z (only supports up to 26 columns for now)
+    return String.fromCharCode(65 + index);
+}
+export function defineModel(sheetName, fields) {
+    const entries = Object.entries(fields);
+    // Validate
+    if (entries.length === 0) {
+        throw schemaError("defineModel requires at least one field");
+    }
+    const primaryKeys = entries.filter(([, f]) => f._isPrimaryKey);
+    if (primaryKeys.length === 0) {
+        throw schemaError("defineModel requires exactly one field marked as primaryKey");
+    }
+    if (primaryKeys.length > 1) {
+        throw schemaError(`defineModel requires exactly one primaryKey, found ${primaryKeys.length}: ${primaryKeys.map(([n]) => n).join(", ")}`);
+    }
+    const headers = entries.map(([name]) => name);
+    const lastCol = columnLetter(headers.length - 1);
+    const primaryKeyName = primaryKeys[0][0];
+    // Build FieldDefinition array
+    const fieldDefs = entries.map(([name, f]) => ({
+        name,
+        type: f._type,
+        isPrimaryKey: f._isPrimaryKey || undefined,
+        isOptional: f._isOptional || undefined,
+        defaultValue: f._defaultValue,
+        references: f._references,
+    }));
+    // Build RelationDefinition array
+    const relations = entries
+        .filter(([, f]) => f._references)
+        .map(([name, f]) => ({
+        sourceField: name,
+        targetModel: f._references.model,
+        targetField: f._references.field,
+        type: "many-to-one",
+    }));
+    // Parse a single cell value based on field type
+    function parseCell(value, fieldEntry) {
+        const [, f] = fieldEntry;
+        const isEmpty = value === undefined || value === null || value === "";
+        // Use default if available and cell is empty
+        if (isEmpty && f._defaultValue !== undefined) {
+            return f._defaultValue;
+        }
+        switch (f._type) {
+            case "string":
+            case "date":
+                return isEmpty ? (f._isOptional ? null : "") : String(value);
+            case "number":
+                return isEmpty ? (f._isOptional ? null : 0) : Number(value);
+            case "boolean":
+                if (value === true || value === "TRUE" || value === "true")
+                    return true;
+                return false;
+        }
+    }
+    const schema = {
+        sheetName,
+        headers,
+        readRange: `${sheetName}!A2:${lastCol}`,
+        writeRange: `${sheetName}!A1:${lastCol}`,
+        clearRange: `${sheetName}!A2:${lastCol}`,
+        primaryKey: primaryKeyName,
+        fields: fieldDefs,
+        relations: relations.length > 0 ? relations : undefined,
+        parseRow(row, _rowIndex) {
+            // Skip rows where first cell is empty
+            const firstCell = row[0];
+            if (firstCell === undefined || firstCell === null || String(firstCell).trim() === "") {
+                return null;
+            }
+            const entity = {};
+            for (let i = 0; i < entries.length; i++) {
+                const value = i < row.length ? row[i] : undefined;
+                entity[entries[i][0]] = parseCell(value, entries[i]);
+            }
+            return entity;
+        },
+        toRow(entity) {
+            return headers.map((h) => entity[h]);
+        },
+        validate(entity) {
+            const issues = [];
+            for (const [name, f] of entries) {
+                const value = entity[name];
+                if (!f._isOptional && (value === null || value === undefined)) {
+                    issues.push({
+                        field: name,
+                        message: `Required field "${name}" is missing or null`,
+                        value,
+                    });
+                }
+            }
+            if (issues.length > 0) {
+                throw validationError(`Validation failed: ${issues.map((i) => i.message).join(", ")}`, issues);
+            }
+        },
+    };
+    return schema;
+}
+//# sourceMappingURL=model.js.map

package/dist/model.js.map

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

package/dist/relations.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Relations module for the genjutsu-db library.
+ * Provides FK validation on write and eager loading via include.
+ */
+import type { SheetSchema } from "./types";
+import type { TransportContext } from "./transport";
+/**
+ * Validate foreign key references for a record before write.
+ * Reads the target model's sheet and checks if the referenced record exists.
+ */
+export declare function validateForeignKeys<T>(record: T, schema: SheetSchema<T>, allSchemas: Record<string, SheetSchema<any>>, ctx: TransportContext, changedFields?: Set<string>): Promise<void>;
+/**
+ * Load related records for a set of parent records using batchGet.
+ * Attaches related records as arrays on each parent by matching FK values.
+ */
+export declare function loadRelated<T>(records: T[], schema: SheetSchema<T>, includeMap: Record<string, true>, allSchemas: Record<string, SheetSchema<any>>, ctx: TransportContext): Promise<T[]>;
+//# sourceMappingURL=relations.d.ts.map

package/dist/relations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relations.d.ts","sourceRoot":"","sources":["../src/relations.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAsB,MAAM,SAAS,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAIpD;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EACtB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,EAC5C,GAAG,EAAE,gBAAgB,EACrB,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAC1B,OAAO,CAAC,IAAI,CAAC,CAyCf;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,OAAO,EAAE,CAAC,EAAE,EACZ,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EACtB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,EAChC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,EAC5C,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,CAAC,EAAE,CAAC,CAyDd"}

package/dist/relations.js

@@ -0,0 +1,114 @@
+/**
+ * Relations module for the genjutsu-db library.
+ * Provides FK validation on write and eager loading via include.
+ */
+import { getSheetValues, batchGetValues } from "./transport";
+import { validationError } from "./errors";
+/**
+ * Validate foreign key references for a record before write.
+ * Reads the target model's sheet and checks if the referenced record exists.
+ */
+export async function validateForeignKeys(record, schema, allSchemas, ctx, changedFields) {
+    if (!schema.relations || schema.relations.length === 0)
+        return;
+    for (const relation of schema.relations) {
+        // If changedFields is provided (for update), only validate changed FK fields
+        if (changedFields && !changedFields.has(relation.sourceField))
+            continue;
+        const fkValue = record[relation.sourceField];
+        if (fkValue === null || fkValue === undefined)
+            continue;
+        // Find the target schema by model key
+        const targetSchema = allSchemas[relation.targetModel];
+        if (!targetSchema)
+            continue; // Should have been caught at registration time
+        // Read target model's data
+        const rows = await getSheetValues(ctx, targetSchema.readRange, "UNFORMATTED_VALUE");
+        const targetPk = targetSchema.primaryKey ?? relation.targetField;
+        // Find the PK column index
+        const pkIndex = targetSchema.headers.indexOf(targetPk);
+        if (pkIndex === -1)
+            continue;
+        // Check if the referenced record exists
+        const exists = rows.some((row) => {
+            const cellValue = row[pkIndex];
+            return cellValue !== undefined && cellValue !== null && String(cellValue) === String(fkValue);
+        });
+        if (!exists) {
+            throw validationError(`Foreign key validation failed: ${relation.sourceField} references ${relation.targetModel}.${relation.targetField} but value "${String(fkValue)}" not found`, [
+                {
+                    field: relation.sourceField,
+                    message: `Referenced ${relation.targetModel}.${relation.targetField} "${String(fkValue)}" not found`,
+                    value: fkValue,
+                },
+            ]);
+        }
+    }
+}
+/**
+ * Load related records for a set of parent records using batchGet.
+ * Attaches related records as arrays on each parent by matching FK values.
+ */
+export async function loadRelated(records, schema, includeMap, allSchemas, ctx) {
+    if (!includeMap || Object.keys(includeMap).length === 0)
+        return records;
+    // Find all related schemas that should be loaded
+    const relatedRanges = [];
+    const relatedSchemaKeys = [];
+    for (const includeKey of Object.keys(includeMap)) {
+        const relatedSchema = allSchemas[includeKey];
+        if (!relatedSchema)
+            continue;
+        relatedRanges.push(relatedSchema.readRange);
+        relatedSchemaKeys.push(includeKey);
+    }
+    if (relatedRanges.length === 0)
+        return records;
+    // Use batchGet for all related schemas at once
+    const batchResult = await batchGetValues(ctx, relatedRanges, "UNFORMATTED_VALUE");
+    // For each related schema, find the relation pointing to the current schema
+    const pk = schema.primaryKey;
+    if (!pk)
+        return records;
+    // Build a map of parent PK values to their records for fast lookup
+    const enhancedRecords = records.map((r) => ({ ...r }));
+    for (let i = 0; i < relatedSchemaKeys.length; i++) {
+        const relatedKey = relatedSchemaKeys[i];
+        const relatedSchema = allSchemas[relatedKey];
+        // Find the relation in the related schema that points to the current model
+        const relation = findRelationToModel(relatedSchema, allSchemas, schema);
+        // Parse the related rows
+        const range = relatedRanges[i];
+        const rows = batchResult.get(range) ?? [];
+        const relatedRecords = [];
+        for (let j = 0; j < rows.length; j++) {
+            const entity = relatedSchema.parseRow(rows[j], j);
+            if (entity != null)
+                relatedRecords.push(entity);
+        }
+        // Attach related records to each parent
+        for (const parent of enhancedRecords) {
+            const parentPk = parent[pk];
+            if (relation) {
+                parent[relatedKey] = relatedRecords.filter((child) => String(child[relation.sourceField]) === String(parentPk));
+            }
+            else {
+                parent[relatedKey] = [];
+            }
+        }
+    }
+    return enhancedRecords;
+}
+/**
+ * Find a relation in the related schema that points back to the current model.
+ */
+function findRelationToModel(relatedSchema, allSchemas, targetSchema) {
+    if (!relatedSchema.relations)
+        return undefined;
+    // Find which key in allSchemas corresponds to targetSchema
+    const targetKey = Object.entries(allSchemas).find(([, s]) => s.sheetName === targetSchema.sheetName)?.[0];
+    if (!targetKey)
+        return undefined;
+    return relatedSchema.relations.find((r) => r.targetModel === targetKey);
+}
+//# sourceMappingURL=relations.js.map

package/dist/relations.js.map

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

package/dist/transport.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Low-level HTTP transport for Google Sheets v4 REST API.
+ * Supports token provider pattern, 401 retry, 403→PERMISSION_ERROR, apiKey for public sheets.
+ */
+export declare const SHEETS_API = "https://sheets.googleapis.com/v4/spreadsheets";
+export interface TransportContext {
+    auth?: string | (() => Promise<string>);
+    apiKey?: string;
+    spreadsheetId: string;
+}
+export declare function extractSpreadsheetId(urlOrId: string): string | null;
+export declare function getSheetValues(ctx: TransportContext, range: string, valueRenderOption?: "FORMATTED_VALUE" | "UNFORMATTED_VALUE"): Promise<unknown[][]>;
+export declare function batchGetValues(ctx: TransportContext, ranges: string[], valueRenderOption?: "FORMATTED_VALUE" | "UNFORMATTED_VALUE"): Promise<Map<string, unknown[][]>>;
+export declare function updateSheet(ctx: TransportContext, range: string, values: unknown[][], append: boolean): Promise<void>;
+export declare function clearRange(ctx: TransportContext, range: string): Promise<void>;
+export declare function batchClear(ctx: TransportContext, ranges: string[]): Promise<void>;
+export declare function batchUpdate(ctx: TransportContext, data: {
+    range: string;
+    values: unknown[][];
+}[]): Promise<void>;
+export declare function getSpreadsheetMetadata(ctx: TransportContext): Promise<{
+    sheets: {
+        sheetId: number;
+        title: string;
+    }[];
+}>;
+export declare function structuralBatchUpdate(ctx: TransportContext, requests: Record<string, unknown>[]): Promise<void>;
+export declare function createSpreadsheet(title: string, auth: string | (() => Promise<string>)): Promise<{
+    spreadsheetId: string;
+    spreadsheetUrl: string;
+}>;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH,eAAO,MAAM,UAAU,kDAAkD,CAAC;AAE1E,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;CACvB;AAMD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMnE;AA6GD,wBAAsB,cAAc,CAClC,GAAG,EAAE,gBAAgB,EACrB,KAAK,EAAE,MAAM,EACb,iBAAiB,GAAE,iBAAiB,GAAG,mBAAuC,GAC7E,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAUtB;AAED,wBAAsB,cAAc,CAClC,GAAG,EAAE,gBAAgB,EACrB,MAAM,EAAE,MAAM,EAAE,EAChB,iBAAiB,GAAE,iBAAiB,GAAG,mBAAuC,GAC7E,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,CAmBnC;AAMD,wBAAsB,WAAW,CAC/B,GAAG,EAAE,gBAAgB,EACrB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,OAAO,EAAE,EAAE,EACnB,MAAM,EAAE,OAAO,GACd,OAAO,CAAC,IAAI,CAAC,CAUf;AAED,wBAAsB,UAAU,CAC9B,GAAG,EAAE,gBAAgB,EACrB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAOf;AAMD,wBAAsB,UAAU,CAC9B,GAAG,EAAE,gBAAgB,EACrB,MAAM,EAAE,MAAM,EAAE,GACf,OAAO,CAAC,IAAI,CAAC,CAaf;AAED,wBAAsB,WAAW,CAC/B,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,EAAE,EAAE,CAAA;CAAE,EAAE,GAC7C,OAAO,CAAC,IAAI,CAAC,CAgBf;AAMD,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC;IAAE,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAAE,CAAC,CAc3D;AAMD,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,gBAAgB,EACrB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAClC,OAAO,CAAC,IAAI,CAAC,CAWf;AAMD,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,GACrC,OAAO,CAAC;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAAC,CAsB5D"}