@fragno-dev/db 0.0.1 → 0.1.0

package/dist/query/query.d.ts

@@ -0,0 +1,79 @@
+import { AnySchema, AnyTable, FragnoId, IdColumn, Relation } from "../schema/create.js";
+import { Condition, ConditionBuilder } from "./condition-builder.js";
+import { DeleteBuilder, FindBuilder, UnitOfWork, UpdateBuilder, UpdateManyBuilder } from "./unit-of-work.js";
+import { Prettify } from "../util/types.js";
+
+//#region src/query/query.d.ts
+type AnySelectClause = SelectClause<AnyTable>;
+type SelectClause<T extends AnyTable> = true | (keyof T["columns"])[];
+type RawColumnValues<T extends AnyTable> = { [K in keyof T["columns"] as string extends K ? never : K]: T["columns"][K]["$out"] };
+type TableToColumnValues<T extends AnyTable> = RawColumnValues<T>;
+type PickNullable<T> = { [P in keyof T as null extends T[P] ? P : never]: T[P] };
+type PickNotNullable<T> = { [P in keyof T as null extends T[P] ? never : P]: T[P] };
+type RawInsertValues<T extends AnyTable> = { [K in keyof T["columns"] as string extends K ? never : K]: T["columns"][K]["$in"] };
+type TableToInsertValues<T extends AnyTable> = Prettify<Partial<PickNullable<RawInsertValues<T>>> & PickNotNullable<RawInsertValues<T>>>;
+type TableToUpdateValues<T extends AnyTable> = { [K in keyof T["columns"] as string extends K ? never : K]?: T["columns"][K] extends IdColumn ? never : T["columns"][K]["$in"] };
+type MainSelectResult<S extends SelectClause<T>, T extends AnyTable> = S extends true ? TableToColumnValues<T> : S extends (keyof T["columns"])[] ? { [K in S[number] as string extends K ? never : K]: K extends keyof T["columns"] ? T["columns"][K]["$out"] : never } : never;
+type SelectResult<T extends AnyTable, JoinOut$1, Select$1 extends SelectClause<T>> = MainSelectResult<Select$1, T> & JoinOut$1;
+interface MapRelationType<Type$1> {
+  one: Type$1 | null;
+  many: Type$1[];
+}
+type JoinBuilder<T extends AnyTable, Out = {}> = { [K in keyof T["relations"]]: T["relations"][K] extends Relation<infer Type, infer Target> ? <Select extends SelectClause<Target> = true, JoinOut = {}>(options?: FindManyOptions<Target, Select, JoinOut, false>) => JoinBuilder<T, Out & { [$K in K]: MapRelationType<SelectResult<Target, JoinOut, Select>>[Type] }> : never };
+type OrderBy<Column = string> = [columnName: Column, "asc" | "desc"];
+type FindFirstOptions<T extends AnyTable = AnyTable, Select$1 extends SelectClause<T> = SelectClause<T>, JoinOut$1 = {}, IsRoot extends boolean = true> = Omit<FindManyOptions<T, Select$1, JoinOut$1, IsRoot>, IsRoot extends true ? "limit" : "limit" | "offset" | "orderBy">;
+type FindManyOptions<T extends AnyTable = AnyTable, Select$1 extends SelectClause<T> = SelectClause<T>, _JoinOut = {}, IsRoot extends boolean = true> = {
+  select?: Select$1;
+  where?: (eb: ConditionBuilder<T["columns"]>) => Condition | boolean;
+  limit?: number;
+  orderBy?: OrderBy<keyof T["columns"]> | OrderBy<keyof T["columns"]>[];
+  join?: (jb: JoinBuilder<T>) => void;
+} & (IsRoot extends true ? {
+  offset?: number;
+} : {});
+interface AbstractQuery<TSchema extends AnySchema, TUOWConfig = void> {
+  /**
+   * Find multiple records using a builder pattern
+   */
+  find: <TableName extends keyof TSchema["tables"] & string, Select extends SelectClause<TSchema["tables"][TableName]> = true, JoinOut = {}>(table: TableName, builderFn?: (builder: Omit<FindBuilder<TSchema["tables"][TableName]>, "build">) => Omit<FindBuilder<TSchema["tables"][TableName], Select, JoinOut>, "build">) => Promise<SelectResult<TSchema["tables"][TableName], JoinOut, Select>[]>;
+  /**
+   * Find the first record matching the criteria
+   * Implemented as a wrapper around find() with pageSize(1)
+   */
+  findFirst: <TableName extends keyof TSchema["tables"] & string, Select extends SelectClause<TSchema["tables"][TableName]> = true, JoinOut = {}>(table: TableName, builderFn?: (builder: Omit<FindBuilder<TSchema["tables"][TableName]>, "build">) => Omit<FindBuilder<TSchema["tables"][TableName], Select, JoinOut>, "build">) => Promise<SelectResult<TSchema["tables"][TableName], JoinOut, Select> | null>;
+  /**
+   * Create a single record
+   * @returns The ID of the created record
+   */
+  create: <TableName extends keyof TSchema["tables"] & string>(table: TableName, values: TableToInsertValues<TSchema["tables"][TableName]>) => Promise<FragnoId>;
+  /**
+   * Create multiple records
+   * @returns Array of IDs of the created records
+   */
+  createMany: <TableName extends keyof TSchema["tables"] & string>(table: TableName, values: TableToInsertValues<TSchema["tables"][TableName]>[]) => Promise<FragnoId[]>;
+  /**
+   * Update a single record by ID
+   * Note: you cannot update the id of a row, some databases don't support that (including MongoDB).
+   */
+  update: <TableName extends keyof TSchema["tables"] & string>(table: TableName, id: FragnoId | string, builderFn: (builder: Omit<UpdateBuilder<TSchema["tables"][TableName]>, "build" | "check">) => Omit<UpdateBuilder<TSchema["tables"][TableName]>, "build">) => Promise<void>;
+  /**
+   * Update multiple records matching a where clause
+   * Note: you cannot update the id of a row, some databases don't support that (including MongoDB).
+   */
+  updateMany: <TableName extends keyof TSchema["tables"] & string>(table: TableName, builderFn: (builder: UpdateManyBuilder<TSchema["tables"][TableName]>) => void) => Promise<void>;
+  /**
+   * Delete a single record by ID
+   */
+  delete: <TableName extends keyof TSchema["tables"] & string>(table: TableName, id: FragnoId | string, builderFn?: (builder: Omit<DeleteBuilder, "build">) => Omit<DeleteBuilder, "build" | "check">) => Promise<void>;
+  /**
+   * Delete multiple records matching a where clause
+   */
+  deleteMany: <TableName extends keyof TSchema["tables"] & string>(table: TableName, builderFn: (builder: Omit<FindBuilder<TSchema["tables"][TableName]>, "build" | "check">) => void) => Promise<void>;
+  /**
+   * Create a Unit of Work bound to this query engine
+   */
+  createUnitOfWork: (name?: string, config?: TUOWConfig) => UnitOfWork<TSchema, []>;
+}
+//#endregion
+export { AbstractQuery, AnySelectClause, FindFirstOptions, FindManyOptions, JoinBuilder, OrderBy, RawColumnValues, SelectClause, SelectResult, TableToColumnValues, TableToInsertValues, TableToUpdateValues };
+//# sourceMappingURL=query.d.ts.map

package/dist/query/query.d.ts.map

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

package/dist/query/query.js

@@ -0,0 +1 @@
+export {  };

package/dist/query/result-transform.js

@@ -0,0 +1,155 @@
+import { createId } from "../id.js";
+import { FragnoId, FragnoReference } from "../schema/create.js";
+import { deserialize, serialize } from "../schema/serialize.js";
+
+//#region src/query/result-transform.ts
+/**
+* Marker class for reference column values that need subquery resolution.
+* When a reference column receives a string (external ID), this marker tells
+* the query builder to generate a subquery to look up the internal ID.
+* @internal
+*/
+var ReferenceSubquery = class {
+	#referencedTable;
+	#externalIdValue;
+	constructor(referencedTable, externalIdValue) {
+		this.#referencedTable = referencedTable;
+		this.#externalIdValue = externalIdValue;
+	}
+	get referencedTable() {
+		return this.#referencedTable;
+	}
+	get externalIdValue() {
+		return this.#externalIdValue;
+	}
+};
+/**
+* Generate a runtime default value for a column that has defaultTo$()
+*
+* Only generates values for runtime defaults (defaultTo$), NOT static defaults (defaultTo).
+* Static defaults should be handled by the database via DEFAULT constraints.
+*
+* @param column - The column with a default value configuration
+* @returns The generated default value, or undefined if the column has no runtime default
+*
+* @internal
+*/
+function generateRuntimeDefault(column) {
+	if (!column.default) return;
+	if ("value" in column.default) return;
+	const runtime = column.default.runtime;
+	if (runtime === "auto") return createId();
+	if (runtime === "now") return /* @__PURE__ */ new Date();
+	if (typeof runtime === "function") return runtime();
+}
+/**
+* Encodes a record of values from the application format to database format.
+*
+* This function transforms object keys to match SQL column names and serializes
+* values according to the database provider's requirements (e.g., converting
+* JavaScript Date objects to numbers for SQLite).
+*
+* @param values - The record of values to encode in application format
+* @param table - The table schema definition containing column information
+* @param generateDefault - Whether to generate default values for undefined columns
+* @param provider - The SQL provider (sqlite, postgresql, mysql, etc.)
+* @returns A record with database-compatible column names and serialized values
+*
+* @example
+* ```ts
+* const encoded = encodeValues(
+*   { userId: 123, createdAt: new Date() },
+*   userTable,
+*   true,
+*   'sqlite'
+* );
+* // Returns: { user_id: 123, created_at: 1234567890 }
+* ```
+*/
+function encodeValues(values, table, generateDefault, provider) {
+	const result = {};
+	for (const k in table.columns) {
+		const col = table.columns[k];
+		if (col.role === "internal-id") continue;
+		let value = values[k];
+		if (generateDefault && value === void 0) value = generateRuntimeDefault(col);
+		if (value !== void 0) {
+			if (col.role === "reference" && typeof value === "string") {
+				const relation = Object.values(table.relations).find((rel) => rel.on.some(([localCol]) => localCol === k));
+				if (relation) {
+					result[col.name] = new ReferenceSubquery(relation.table, value);
+					continue;
+				}
+				throw new Error(`Reference column ${k} not found in table ${table.name}`);
+			}
+			result[col.name] = serialize(value, col, provider);
+		}
+	}
+	return result;
+}
+/**
+* Decodes a database result record to application format.
+*
+* This function transforms database column names back to application property names
+* and deserializes values according to the database provider's format (e.g., converting
+* SQLite integers back to JavaScript Date objects).
+*
+* Supports relation data encoded with the pattern `relationName:columnName`.
+*
+* @param result - The raw database result record
+* @param table - The table schema definition containing column and relation information
+* @param provider - The SQL provider (sqlite, postgresql, mysql, etc.)
+* @returns A record in application format with deserialized values
+*
+* @example
+* ```ts
+* const decoded = decodeResult(
+*   { user_id: 123, created_at: 1234567890, 'posts:title': 'Hello' },
+*   userTable,
+*   'sqlite'
+* );
+* // Returns: { userId: 123, createdAt: Date, posts: { title: 'Hello' } }
+* ```
+*/
+function decodeResult(result, table, provider) {
+	const output = {};
+	const columnValues = {};
+	const relationData = {};
+	for (const k in result) {
+		const colonIndex = k.indexOf(":");
+		const value = result[k];
+		if (colonIndex === -1) {
+			const col = table.columns[k];
+			if (!col) continue;
+			columnValues[k] = deserialize(value, col, provider);
+			continue;
+		}
+		const relationName = k.slice(0, colonIndex);
+		const remainder = k.slice(colonIndex + 1);
+		if (table.relations[relationName] === void 0) continue;
+		relationData[relationName] ??= {};
+		relationData[relationName][remainder] = value;
+	}
+	for (const relationName in relationData) {
+		const relation = table.relations[relationName];
+		if (!relation) continue;
+		output[relationName] = decodeResult(relationData[relationName], relation.table, provider);
+	}
+	for (const k in columnValues) {
+		const col = table.columns[k];
+		if (!col) continue;
+		if (col.isHidden) continue;
+		if (col.role === "external-id" && columnValues["_internalId"] !== void 0) output[k] = new FragnoId({
+			externalId: columnValues[k],
+			internalId: columnValues["_internalId"],
+			version: columnValues["_version"]
+		});
+		else if (col.role === "reference") output[k] = FragnoReference.fromInternal(columnValues[k]);
+		else output[k] = columnValues[k];
+	}
+	return output;
+}
+
+//#endregion
+export { ReferenceSubquery, decodeResult, encodeValues };
+//# sourceMappingURL=result-transform.js.map

package/dist/query/result-transform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-transform.js","names":["#referencedTable","#externalIdValue","result: Record<string, unknown>","output: Record<string, unknown>","columnValues: Record<string, unknown>","relationData: Record<string, Record<string, unknown>>"],"sources":["../../src/query/result-transform.ts"],"sourcesContent":["import type { AnyColumn, AnyTable } from \"../schema/create\";\nimport type { SQLProvider } from \"../shared/providers\";\nimport { deserialize, serialize } from \"../schema/serialize\";\nimport { FragnoId, FragnoReference } from \"../schema/create\";\nimport { createId } from \"../id\";\n\n/**\n * Marker class for reference column values that need subquery resolution.\n * When a reference column receives a string (external ID), this marker tells\n * the query builder to generate a subquery to look up the internal ID.\n * @internal\n */\nexport class ReferenceSubquery {\n  #referencedTable: AnyTable;\n  #externalIdValue: string;\n\n  constructor(referencedTable: AnyTable, externalIdValue: string) {\n    this.#referencedTable = referencedTable;\n    this.#externalIdValue = externalIdValue;\n  }\n\n  get referencedTable() {\n    return this.#referencedTable;\n  }\n\n  get externalIdValue() {\n    return this.#externalIdValue;\n  }\n}\n\n/**\n * Generate a runtime default value for a column that has defaultTo$()\n *\n * Only generates values for runtime defaults (defaultTo$), NOT static defaults (defaultTo).\n * Static defaults should be handled by the database via DEFAULT constraints.\n *\n * @param column - The column with a default value configuration\n * @returns The generated default value, or undefined if the column has no runtime default\n *\n * @internal\n */\nexport function generateRuntimeDefault(column: AnyColumn): unknown {\n  // Check if column has a default value configuration\n  if (!column.default) {\n    return undefined;\n  }\n\n  // If it's a static default value (defaultTo), return undefined\n  // as the database should handle this via DEFAULT constraint\n  if (\"value\" in column.default) {\n    return undefined;\n  }\n\n  // Handle runtime defaults (defaultTo$)\n  const runtime = column.default.runtime;\n\n  if (runtime === \"auto\") {\n    return createId();\n  }\n\n  if (runtime === \"now\") {\n    return new Date();\n  }\n\n  if (typeof runtime === \"function\") {\n    return runtime();\n  }\n\n  return undefined;\n}\n\n/**\n * Encodes a record of values from the application format to database format.\n *\n * This function transforms object keys to match SQL column names and serializes\n * values according to the database provider's requirements (e.g., converting\n * JavaScript Date objects to numbers for SQLite).\n *\n * @param values - The record of values to encode in application format\n * @param table - The table schema definition containing column information\n * @param generateDefault - Whether to generate default values for undefined columns\n * @param provider - The SQL provider (sqlite, postgresql, mysql, etc.)\n * @returns A record with database-compatible column names and serialized values\n *\n * @example\n * ```ts\n * const encoded = encodeValues(\n *   { userId: 123, createdAt: new Date() },\n *   userTable,\n *   true,\n *   'sqlite'\n * );\n * // Returns: { user_id: 123, created_at: 1234567890 }\n * ```\n */\nexport function encodeValues(\n  values: Record<string, unknown>,\n  table: AnyTable,\n  generateDefault: boolean,\n  provider: SQLProvider,\n): Record<string, unknown> {\n  const result: Record<string, unknown> = {};\n\n  for (const k in table.columns) {\n    const col = table.columns[k];\n\n    // Skip internal ID - never provided by user, auto-generated by database\n    if (col.role === \"internal-id\") {\n      continue;\n    }\n    let value = values[k];\n\n    if (generateDefault && value === undefined) {\n      // Only generate runtime defaults (defaultTo$), not static defaults (defaultTo).\n      // Static defaults should be handled by the database via DEFAULT constraints.\n      value = generateRuntimeDefault(col);\n    }\n\n    if (value !== undefined) {\n      // Handle string references - convert external ID to internal ID via subquery\n      if (col.role === \"reference\" && typeof value === \"string\") {\n        // Find relation that uses this column\n        const relation = Object.values(table.relations).find((rel) =>\n          rel.on.some(([localCol]) => localCol === k),\n        );\n        if (relation) {\n          result[col.name] = new ReferenceSubquery(relation.table, value);\n          continue;\n        }\n\n        throw new Error(`Reference column ${k} not found in table ${table.name}`);\n      }\n\n      result[col.name] = serialize(value, col, provider);\n    }\n  }\n\n  return result;\n}\n\n/**\n * Decodes a database result record to application format.\n *\n * This function transforms database column names back to application property names\n * and deserializes values according to the database provider's format (e.g., converting\n * SQLite integers back to JavaScript Date objects).\n *\n * Supports relation data encoded with the pattern `relationName:columnName`.\n *\n * @param result - The raw database result record\n * @param table - The table schema definition containing column and relation information\n * @param provider - The SQL provider (sqlite, postgresql, mysql, etc.)\n * @returns A record in application format with deserialized values\n *\n * @example\n * ```ts\n * const decoded = decodeResult(\n *   { user_id: 123, created_at: 1234567890, 'posts:title': 'Hello' },\n *   userTable,\n *   'sqlite'\n * );\n * // Returns: { userId: 123, createdAt: Date, posts: { title: 'Hello' } }\n * ```\n */\nexport function decodeResult(\n  result: Record<string, unknown>,\n  table: AnyTable,\n  provider: SQLProvider,\n): Record<string, unknown> {\n  const output: Record<string, unknown> = {};\n  // First pass: collect all column values\n  const columnValues: Record<string, unknown> = {};\n\n  // Collect all relation data (including nested) keyed by relation name\n  const relationData: Record<string, Record<string, unknown>> = {};\n\n  for (const k in result) {\n    const colonIndex = k.indexOf(\":\");\n    const value = result[k];\n\n    // Direct column (no colon)\n    if (colonIndex === -1) {\n      const col = table.columns[k];\n      if (!col) {\n        continue;\n      }\n\n      // Store all column values (including hidden ones for FragnoId creation)\n      columnValues[k] = deserialize(value, col, provider);\n      continue;\n    }\n\n    // Relation column (has colon)\n    const relationName = k.slice(0, colonIndex);\n    const remainder = k.slice(colonIndex + 1);\n\n    const relation = table.relations[relationName];\n    if (relation === undefined) {\n      continue;\n    }\n\n    // Collect relation data with the remaining key path\n    relationData[relationName] ??= {};\n    relationData[relationName][remainder] = value;\n  }\n\n  // Process each relation's data recursively\n  for (const relationName in relationData) {\n    const relation = table.relations[relationName];\n    if (!relation) {\n      continue;\n    }\n\n    // Recursively decode the relation data\n    output[relationName] = decodeResult(relationData[relationName], relation.table, provider);\n  }\n\n  // Second pass: create output with FragnoId objects where appropriate\n  for (const k in columnValues) {\n    const col = table.columns[k];\n    if (!col) {\n      continue;\n    }\n\n    // Filter out hidden columns (like _internalId, _version) from results\n    if (col.isHidden) {\n      continue;\n    }\n\n    // For external ID columns, create FragnoId if we have both external and internal IDs\n    if (col.role === \"external-id\" && columnValues[\"_internalId\"] !== undefined) {\n      output[k] = new FragnoId({\n        externalId: columnValues[k] as string,\n        internalId: columnValues[\"_internalId\"] as bigint,\n        // _version is always selected as a hidden column, so it should always be present\n        version: columnValues[\"_version\"] as number,\n      });\n    } else if (col.role === \"reference\") {\n      // For reference columns, create FragnoReference with internal ID\n      output[k] = FragnoReference.fromInternal(columnValues[k] as bigint);\n    } else {\n      output[k] = columnValues[k];\n    }\n  }\n\n  return output;\n}\n"],"mappings":";;;;;;;;;;;AAYA,IAAa,oBAAb,MAA+B;CAC7B;CACA;CAEA,YAAY,iBAA2B,iBAAyB;AAC9D,QAAKA,kBAAmB;AACxB,QAAKC,kBAAmB;;CAG1B,IAAI,kBAAkB;AACpB,SAAO,MAAKD;;CAGd,IAAI,kBAAkB;AACpB,SAAO,MAAKC;;;;;;;;;;;;;;AAehB,SAAgB,uBAAuB,QAA4B;AAEjE,KAAI,CAAC,OAAO,QACV;AAKF,KAAI,WAAW,OAAO,QACpB;CAIF,MAAM,UAAU,OAAO,QAAQ;AAE/B,KAAI,YAAY,OACd,QAAO,UAAU;AAGnB,KAAI,YAAY,MACd,wBAAO,IAAI,MAAM;AAGnB,KAAI,OAAO,YAAY,WACrB,QAAO,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BpB,SAAgB,aACd,QACA,OACA,iBACA,UACyB;CACzB,MAAMC,SAAkC,EAAE;AAE1C,MAAK,MAAM,KAAK,MAAM,SAAS;EAC7B,MAAM,MAAM,MAAM,QAAQ;AAG1B,MAAI,IAAI,SAAS,cACf;EAEF,IAAI,QAAQ,OAAO;AAEnB,MAAI,mBAAmB,UAAU,OAG/B,SAAQ,uBAAuB,IAAI;AAGrC,MAAI,UAAU,QAAW;AAEvB,OAAI,IAAI,SAAS,eAAe,OAAO,UAAU,UAAU;IAEzD,MAAM,WAAW,OAAO,OAAO,MAAM,UAAU,CAAC,MAAM,QACpD,IAAI,GAAG,MAAM,CAAC,cAAc,aAAa,EAAE,CAC5C;AACD,QAAI,UAAU;AACZ,YAAO,IAAI,QAAQ,IAAI,kBAAkB,SAAS,OAAO,MAAM;AAC/D;;AAGF,UAAM,IAAI,MAAM,oBAAoB,EAAE,sBAAsB,MAAM,OAAO;;AAG3E,UAAO,IAAI,QAAQ,UAAU,OAAO,KAAK,SAAS;;;AAItD,QAAO;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BT,SAAgB,aACd,QACA,OACA,UACyB;CACzB,MAAMC,SAAkC,EAAE;CAE1C,MAAMC,eAAwC,EAAE;CAGhD,MAAMC,eAAwD,EAAE;AAEhE,MAAK,MAAM,KAAK,QAAQ;EACtB,MAAM,aAAa,EAAE,QAAQ,IAAI;EACjC,MAAM,QAAQ,OAAO;AAGrB,MAAI,eAAe,IAAI;GACrB,MAAM,MAAM,MAAM,QAAQ;AAC1B,OAAI,CAAC,IACH;AAIF,gBAAa,KAAK,YAAY,OAAO,KAAK,SAAS;AACnD;;EAIF,MAAM,eAAe,EAAE,MAAM,GAAG,WAAW;EAC3C,MAAM,YAAY,EAAE,MAAM,aAAa,EAAE;AAGzC,MADiB,MAAM,UAAU,kBAChB,OACf;AAIF,eAAa,kBAAkB,EAAE;AACjC,eAAa,cAAc,aAAa;;AAI1C,MAAK,MAAM,gBAAgB,cAAc;EACvC,MAAM,WAAW,MAAM,UAAU;AACjC,MAAI,CAAC,SACH;AAIF,SAAO,gBAAgB,aAAa,aAAa,eAAe,SAAS,OAAO,SAAS;;AAI3F,MAAK,MAAM,KAAK,cAAc;EAC5B,MAAM,MAAM,MAAM,QAAQ;AAC1B,MAAI,CAAC,IACH;AAIF,MAAI,IAAI,SACN;AAIF,MAAI,IAAI,SAAS,iBAAiB,aAAa,mBAAmB,OAChE,QAAO,KAAK,IAAI,SAAS;GACvB,YAAY,aAAa;GACzB,YAAY,aAAa;GAEzB,SAAS,aAAa;GACvB,CAAC;WACO,IAAI,SAAS,YAEtB,QAAO,KAAK,gBAAgB,aAAa,aAAa,GAAa;MAEnE,QAAO,KAAK,aAAa;;AAI7B,QAAO"}