@tanstack/powersync-db-collection 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kyle Mathews
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cjs/PendingOperationStore.cjs

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const pDefer = require("p-defer");
+const _PendingOperationStore = class _PendingOperationStore {
+  constructor() {
+    this.pendingOperations = /* @__PURE__ */ new Map();
+  }
+  /**
+   * @returns A promise which will resolve once the specified operation has been seen.
+   */
+  waitFor(operation) {
+    const managedPromise = pDefer();
+    this.pendingOperations.set(operation, managedPromise);
+    return managedPromise.promise;
+  }
+  /**
+   * Marks a set of operations as seen. This will resolve any pending promises.
+   */
+  resolvePendingFor(operations) {
+    for (const operation of operations) {
+      for (const [pendingOp, deferred] of this.pendingOperations.entries()) {
+        if (pendingOp.tableName == operation.tableName && pendingOp.operation == operation.operation && pendingOp.id == operation.id && pendingOp.timestamp == operation.timestamp) {
+          deferred.resolve();
+          this.pendingOperations.delete(pendingOp);
+        }
+      }
+    }
+  }
+};
+_PendingOperationStore.GLOBAL = new _PendingOperationStore();
+let PendingOperationStore = _PendingOperationStore;
+exports.PendingOperationStore = PendingOperationStore;
+//# sourceMappingURL=PendingOperationStore.cjs.map

package/dist/cjs/PendingOperationStore.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"PendingOperationStore.cjs","sources":["../../src/PendingOperationStore.ts"],"sourcesContent":["import pDefer from \"p-defer\"\nimport type { DiffTriggerOperation } from \"@powersync/common\"\nimport type { DeferredPromise } from \"p-defer\"\n\nexport type PendingOperation = {\n  tableName: string\n  operation: DiffTriggerOperation\n  id: string\n  timestamp: string\n}\n\n/**\n * Optimistic mutations have their optimistic state discarded once transactions have\n * been applied.\n * We need to ensure that an applied transaction has been observed by the sync diff trigger\n * before resolving the transaction application call.\n * This store allows registering a wait for a pending operation to have been observed.\n */\nexport class PendingOperationStore {\n  private pendingOperations = new Map<PendingOperation, DeferredPromise<void>>()\n\n  /**\n   * Globally accessible PendingOperationStore\n   */\n  static GLOBAL = new PendingOperationStore()\n\n  /**\n   * @returns A promise which will resolve once the specified operation has been seen.\n   */\n  waitFor(operation: PendingOperation): Promise<void> {\n    const managedPromise = pDefer<void>()\n    this.pendingOperations.set(operation, managedPromise)\n    return managedPromise.promise\n  }\n\n  /**\n   * Marks a set of operations as seen. This will resolve any pending promises.\n   */\n  resolvePendingFor(operations: Array<PendingOperation>) {\n    for (const operation of operations) {\n      for (const [pendingOp, deferred] of this.pendingOperations.entries()) {\n        if (\n          pendingOp.tableName == operation.tableName &&\n          pendingOp.operation == operation.operation &&\n          pendingOp.id == operation.id &&\n          pendingOp.timestamp == operation.timestamp\n        ) {\n          deferred.resolve()\n          this.pendingOperations.delete(pendingOp)\n        }\n      }\n    }\n  }\n}\n"],"names":[],"mappings":";;;AAkBO,MAAM,yBAAN,MAAM,uBAAsB;AAAA,EAA5B,cAAA;AACL,SAAQ,wCAAwB,IAAA;AAAA,EAA6C;AAAA;AAAA;AAAA;AAAA,EAU7E,QAAQ,WAA4C;AAClD,UAAM,iBAAiB,OAAA;AACvB,SAAK,kBAAkB,IAAI,WAAW,cAAc;AACpD,WAAO,eAAe;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA,EAKA,kBAAkB,YAAqC;AACrD,eAAW,aAAa,YAAY;AAClC,iBAAW,CAAC,WAAW,QAAQ,KAAK,KAAK,kBAAkB,WAAW;AACpE,YACE,UAAU,aAAa,UAAU,aACjC,UAAU,aAAa,UAAU,aACjC,UAAU,MAAM,UAAU,MAC1B,UAAU,aAAa,UAAU,WACjC;AACA,mBAAS,QAAA;AACT,eAAK,kBAAkB,OAAO,SAAS;AAAA,QACzC;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;AA7BE,uBAAO,SAAS,IAAI,uBAAA;AANf,IAAM,wBAAN;;"}

package/dist/cjs/PendingOperationStore.d.cts

@@ -0,0 +1,29 @@
+import { DiffTriggerOperation } from '@powersync/common';
+export type PendingOperation = {
+    tableName: string;
+    operation: DiffTriggerOperation;
+    id: string;
+    timestamp: string;
+};
+/**
+ * Optimistic mutations have their optimistic state discarded once transactions have
+ * been applied.
+ * We need to ensure that an applied transaction has been observed by the sync diff trigger
+ * before resolving the transaction application call.
+ * This store allows registering a wait for a pending operation to have been observed.
+ */
+export declare class PendingOperationStore {
+    private pendingOperations;
+    /**
+     * Globally accessible PendingOperationStore
+     */
+    static GLOBAL: PendingOperationStore;
+    /**
+     * @returns A promise which will resolve once the specified operation has been seen.
+     */
+    waitFor(operation: PendingOperation): Promise<void>;
+    /**
+     * Marks a set of operations as seen. This will resolve any pending promises.
+     */
+    resolvePendingFor(operations: Array<PendingOperation>): void;
+}

package/dist/cjs/PowerSyncTransactor.cjs

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const common = require("@powersync/common");
+const DebugModule = require("debug");
+const helpers = require("./helpers.cjs");
+const PendingOperationStore = require("./PendingOperationStore.cjs");
+const debug = DebugModule.debug(`ts/db:powersync`);
+class PowerSyncTransactor {
+  constructor(options) {
+    this.database = options.database;
+    this.pendingOperationStore = PendingOperationStore.PendingOperationStore.GLOBAL;
+  }
+  /**
+   * Persists a {@link Transaction} to the PowerSync SQLite database.
+   */
+  async applyTransaction(transaction) {
+    const { mutations } = transaction;
+    if (mutations.length == 0) {
+      return;
+    }
+    const mutationsCollectionIds = mutations.map(
+      (mutation) => mutation.collection.id
+    );
+    const collectionIds = Array.from(new Set(mutationsCollectionIds));
+    const lastCollectionMutationIndexes = /* @__PURE__ */ new Map();
+    const allCollections = collectionIds.map((id) => mutations.find((mutation) => mutation.collection.id == id)).map((mutation) => mutation.collection);
+    for (const collectionId of collectionIds) {
+      lastCollectionMutationIndexes.set(
+        collectionId,
+        mutationsCollectionIds.lastIndexOf(collectionId)
+      );
+    }
+    await Promise.all(
+      allCollections.map(async (collection) => {
+        if (collection.isReady()) {
+          return;
+        }
+        await new Promise((resolve) => collection.onFirstReady(resolve));
+      })
+    );
+    const { whenComplete } = await this.database.writeTransaction(
+      async (tx) => {
+        const pendingOperations = [];
+        for (const [index, mutation] of mutations.entries()) {
+          const shouldWait = index == lastCollectionMutationIndexes.get(mutation.collection.id);
+          switch (mutation.type) {
+            case `insert`:
+              pendingOperations.push(
+                await this.handleInsert(mutation, tx, shouldWait)
+              );
+              break;
+            case `update`:
+              pendingOperations.push(
+                await this.handleUpdate(mutation, tx, shouldWait)
+              );
+              break;
+            case `delete`:
+              pendingOperations.push(
+                await this.handleDelete(mutation, tx, shouldWait)
+              );
+              break;
+          }
+        }
+        return {
+          whenComplete: Promise.all(
+            pendingOperations.filter((op) => !!op).map((op) => this.pendingOperationStore.waitFor(op))
+          )
+        };
+      }
+    );
+    await whenComplete;
+  }
+  async handleInsert(mutation, context, waitForCompletion = false) {
+    debug(`insert`, mutation);
+    return this.handleOperationWithCompletion(
+      mutation,
+      context,
+      waitForCompletion,
+      async (tableName, mutation2, serializeValue) => {
+        const values = serializeValue(mutation2.modified);
+        const keys = Object.keys(values).map((key) => common.sanitizeSQL`${key}`);
+        await context.execute(
+          `
+        INSERT into ${tableName} 
+            (${keys.join(`, `)}) 
+        VALUES 
+            (${keys.map((_) => `?`).join(`, `)})
+        `,
+          Object.values(values)
+        );
+      }
+    );
+  }
+  async handleUpdate(mutation, context, waitForCompletion = false) {
+    debug(`update`, mutation);
+    return this.handleOperationWithCompletion(
+      mutation,
+      context,
+      waitForCompletion,
+      async (tableName, mutation2, serializeValue) => {
+        const values = serializeValue(mutation2.modified);
+        const keys = Object.keys(values).map((key) => common.sanitizeSQL`${key}`);
+        await context.execute(
+          `
+        UPDATE ${tableName} 
+        SET ${keys.map((key) => `${key} = ?`).join(`, `)}
+        WHERE id = ?
+        `,
+          [...Object.values(values), helpers.asPowerSyncRecord(mutation2.modified).id]
+        );
+      }
+    );
+  }
+  async handleDelete(mutation, context, waitForCompletion = false) {
+    debug(`update`, mutation);
+    return this.handleOperationWithCompletion(
+      mutation,
+      context,
+      waitForCompletion,
+      async (tableName, mutation2) => {
+        await context.execute(
+          `
+        DELETE FROM ${tableName} WHERE id = ?
+        `,
+          [helpers.asPowerSyncRecord(mutation2.original).id]
+        );
+      }
+    );
+  }
+  /**
+   * Helper function which wraps a persistence operation by:
+   * - Fetching the mutation's collection's SQLite table details
+   * - Executing the mutation
+   * - Returning the last pending diff operation if required
+   */
+  async handleOperationWithCompletion(mutation, context, waitForCompletion, handler) {
+    if (typeof mutation.collection.config.utils?.getMeta != `function`) {
+      throw new Error(`Could not get tableName from mutation's collection config.
+        The provided mutation might not have originated from PowerSync.`);
+    }
+    const { tableName, trackedTableName, serializeValue } = mutation.collection.config.utils.getMeta();
+    await handler(common.sanitizeSQL`${tableName}`, mutation, serializeValue);
+    if (!waitForCompletion) {
+      return null;
+    }
+    const diffOperation = await context.get(
+      common.sanitizeSQL`SELECT id, timestamp FROM ${trackedTableName} ORDER BY timestamp DESC LIMIT 1`
+    );
+    return {
+      tableName,
+      id: diffOperation.id,
+      operation: helpers.mapOperationToPowerSync(mutation.type),
+      timestamp: diffOperation.timestamp
+    };
+  }
+}
+exports.PowerSyncTransactor = PowerSyncTransactor;
+//# sourceMappingURL=PowerSyncTransactor.cjs.map

package/dist/cjs/PowerSyncTransactor.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"PowerSyncTransactor.cjs","sources":["../../src/PowerSyncTransactor.ts"],"sourcesContent":["import { sanitizeSQL } from \"@powersync/common\"\nimport DebugModule from \"debug\"\nimport { asPowerSyncRecord, mapOperationToPowerSync } from \"./helpers\"\nimport { PendingOperationStore } from \"./PendingOperationStore\"\nimport type { AbstractPowerSyncDatabase, LockContext } from \"@powersync/common\"\nimport type { PendingMutation, Transaction } from \"@tanstack/db\"\nimport type { EnhancedPowerSyncCollectionConfig } from \"./definitions\"\nimport type { PendingOperation } from \"./PendingOperationStore\"\n\nconst debug = DebugModule.debug(`ts/db:powersync`)\n\nexport type TransactorOptions = {\n  database: AbstractPowerSyncDatabase\n}\n\n/**\n * Applies mutations to the PowerSync database. This method is called automatically by the collection's\n * insert, update, and delete operations. You typically don't need to call this directly unless you\n * have special transaction requirements.\n *\n * @example\n * ```typescript\n * // Create a collection\n * const collection = createCollection(\n *   powerSyncCollectionOptions<Document>({\n *     database: db,\n *     table: APP_SCHEMA.props.documents,\n *   })\n * )\n *\n * const addTx = createTransaction({\n *   autoCommit: false,\n *   mutationFn: async ({ transaction }) => {\n *     await new PowerSyncTransactor({ database: db }).applyTransaction(transaction)\n *   },\n * })\n *\n * addTx.mutate(() => {\n *   for (let i = 0; i < 5; i++) {\n *     collection.insert({ id: randomUUID(), name: `tx-${i}` })\n *   }\n * })\n *\n * await addTx.commit()\n * await addTx.isPersisted.promise\n * ```\n *\n * @param transaction - The transaction containing mutations to apply\n * @returns A promise that resolves when the mutations have been persisted to PowerSync\n */\nexport class PowerSyncTransactor {\n  database: AbstractPowerSyncDatabase\n  pendingOperationStore: PendingOperationStore\n\n  constructor(options: TransactorOptions) {\n    this.database = options.database\n    this.pendingOperationStore = PendingOperationStore.GLOBAL\n  }\n\n  /**\n   * Persists a {@link Transaction} to the PowerSync SQLite database.\n   */\n  async applyTransaction(transaction: Transaction<any>) {\n    const { mutations } = transaction\n\n    if (mutations.length == 0) {\n      return\n    }\n    /**\n     * The transaction might contain operations for different collections.\n     * We can do some optimizations for single-collection transactions.\n     */\n    const mutationsCollectionIds = mutations.map(\n      (mutation) => mutation.collection.id\n    )\n    const collectionIds = Array.from(new Set(mutationsCollectionIds))\n    const lastCollectionMutationIndexes = new Map<string, number>()\n    const allCollections = collectionIds\n      .map((id) => mutations.find((mutation) => mutation.collection.id == id)!)\n      .map((mutation) => mutation.collection)\n    for (const collectionId of collectionIds) {\n      lastCollectionMutationIndexes.set(\n        collectionId,\n        mutationsCollectionIds.lastIndexOf(collectionId)\n      )\n    }\n\n    // Check all the observers are ready before taking a lock\n    await Promise.all(\n      allCollections.map(async (collection) => {\n        if (collection.isReady()) {\n          return\n        }\n        await new Promise<void>((resolve) => collection.onFirstReady(resolve))\n      })\n    )\n\n    // Persist to PowerSync\n    const { whenComplete } = await this.database.writeTransaction(\n      async (tx) => {\n        const pendingOperations: Array<PendingOperation | null> = []\n\n        for (const [index, mutation] of mutations.entries()) {\n          /**\n           * Each collection processes events independently. We need to make sure the\n           * last operation for each collection has been observed.\n           */\n          const shouldWait =\n            index == lastCollectionMutationIndexes.get(mutation.collection.id)\n          switch (mutation.type) {\n            case `insert`:\n              pendingOperations.push(\n                await this.handleInsert(mutation, tx, shouldWait)\n              )\n              break\n            case `update`:\n              pendingOperations.push(\n                await this.handleUpdate(mutation, tx, shouldWait)\n              )\n              break\n            case `delete`:\n              pendingOperations.push(\n                await this.handleDelete(mutation, tx, shouldWait)\n              )\n              break\n          }\n        }\n\n        /**\n         * Return a promise from the writeTransaction, without awaiting it.\n         * This promise will resolve once the entire transaction has been\n         * observed via the diff triggers.\n         * We return without awaiting in order to free the write lock.\n         */\n        return {\n          whenComplete: Promise.all(\n            pendingOperations\n              .filter((op) => !!op)\n              .map((op) => this.pendingOperationStore.waitFor(op))\n          ),\n        }\n      }\n    )\n\n    // Wait for the change to be observed via the diff trigger\n    await whenComplete\n  }\n\n  protected async handleInsert(\n    mutation: PendingMutation<any>,\n    context: LockContext,\n    waitForCompletion: boolean = false\n  ): Promise<PendingOperation | null> {\n    debug(`insert`, mutation)\n\n    return this.handleOperationWithCompletion(\n      mutation,\n      context,\n      waitForCompletion,\n      async (tableName, mutation, serializeValue) => {\n        const values = serializeValue(mutation.modified)\n        const keys = Object.keys(values).map((key) => sanitizeSQL`${key}`)\n\n        await context.execute(\n          `\n        INSERT into ${tableName} \n            (${keys.join(`, `)}) \n        VALUES \n            (${keys.map((_) => `?`).join(`, `)})\n        `,\n          Object.values(values)\n        )\n      }\n    )\n  }\n\n  protected async handleUpdate(\n    mutation: PendingMutation<any>,\n    context: LockContext,\n    waitForCompletion: boolean = false\n  ): Promise<PendingOperation | null> {\n    debug(`update`, mutation)\n\n    return this.handleOperationWithCompletion(\n      mutation,\n      context,\n      waitForCompletion,\n      async (tableName, mutation, serializeValue) => {\n        const values = serializeValue(mutation.modified)\n        const keys = Object.keys(values).map((key) => sanitizeSQL`${key}`)\n\n        await context.execute(\n          `\n        UPDATE ${tableName} \n        SET ${keys.map((key) => `${key} = ?`).join(`, `)}\n        WHERE id = ?\n        `,\n          [...Object.values(values), asPowerSyncRecord(mutation.modified).id]\n        )\n      }\n    )\n  }\n\n  protected async handleDelete(\n    mutation: PendingMutation<any>,\n    context: LockContext,\n    waitForCompletion: boolean = false\n  ): Promise<PendingOperation | null> {\n    debug(`update`, mutation)\n\n    return this.handleOperationWithCompletion(\n      mutation,\n      context,\n      waitForCompletion,\n      async (tableName, mutation) => {\n        await context.execute(\n          `\n        DELETE FROM ${tableName} WHERE id = ?\n        `,\n          [asPowerSyncRecord(mutation.original).id]\n        )\n      }\n    )\n  }\n\n  /**\n   * Helper function which wraps a persistence operation by:\n   * - Fetching the mutation's collection's SQLite table details\n   * - Executing the mutation\n   * - Returning the last pending diff operation if required\n   */\n  protected async handleOperationWithCompletion(\n    mutation: PendingMutation<any>,\n    context: LockContext,\n    waitForCompletion: boolean,\n    handler: (\n      tableName: string,\n      mutation: PendingMutation<any>,\n      serializeValue: (value: any) => Record<string, unknown>\n    ) => Promise<void>\n  ): Promise<PendingOperation | null> {\n    if (\n      typeof (mutation.collection.config as any).utils?.getMeta != `function`\n    ) {\n      throw new Error(`Could not get tableName from mutation's collection config.\n        The provided mutation might not have originated from PowerSync.`)\n    }\n\n    const { tableName, trackedTableName, serializeValue } = (\n      mutation.collection\n        .config as unknown as EnhancedPowerSyncCollectionConfig<any>\n    ).utils.getMeta()\n\n    await handler(sanitizeSQL`${tableName}`, mutation, serializeValue)\n\n    if (!waitForCompletion) {\n      return null\n    }\n\n    // Need to get the operation in order to wait for it\n    const diffOperation = await context.get<{ id: string; timestamp: string }>(\n      sanitizeSQL`SELECT id, timestamp FROM ${trackedTableName} ORDER BY timestamp DESC LIMIT 1`\n    )\n    return {\n      tableName,\n      id: diffOperation.id,\n      operation: mapOperationToPowerSync(mutation.type),\n      timestamp: diffOperation.timestamp,\n    }\n  }\n}\n"],"names":["PendingOperationStore","mutation","sanitizeSQL","asPowerSyncRecord","mapOperationToPowerSync"],"mappings":"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"}

package/dist/cjs/PowerSyncTransactor.d.cts

@@ -0,0 +1,60 @@
+import { PendingOperationStore, PendingOperation } from './PendingOperationStore.cjs';
+import { AbstractPowerSyncDatabase, LockContext } from '@powersync/common';
+import { PendingMutation, Transaction } from '@tanstack/db';
+export type TransactorOptions = {
+    database: AbstractPowerSyncDatabase;
+};
+/**
+ * Applies mutations to the PowerSync database. This method is called automatically by the collection's
+ * insert, update, and delete operations. You typically don't need to call this directly unless you
+ * have special transaction requirements.
+ *
+ * @example
+ * ```typescript
+ * // Create a collection
+ * const collection = createCollection(
+ *   powerSyncCollectionOptions<Document>({
+ *     database: db,
+ *     table: APP_SCHEMA.props.documents,
+ *   })
+ * )
+ *
+ * const addTx = createTransaction({
+ *   autoCommit: false,
+ *   mutationFn: async ({ transaction }) => {
+ *     await new PowerSyncTransactor({ database: db }).applyTransaction(transaction)
+ *   },
+ * })
+ *
+ * addTx.mutate(() => {
+ *   for (let i = 0; i < 5; i++) {
+ *     collection.insert({ id: randomUUID(), name: `tx-${i}` })
+ *   }
+ * })
+ *
+ * await addTx.commit()
+ * await addTx.isPersisted.promise
+ * ```
+ *
+ * @param transaction - The transaction containing mutations to apply
+ * @returns A promise that resolves when the mutations have been persisted to PowerSync
+ */
+export declare class PowerSyncTransactor {
+    database: AbstractPowerSyncDatabase;
+    pendingOperationStore: PendingOperationStore;
+    constructor(options: TransactorOptions);
+    /**
+     * Persists a {@link Transaction} to the PowerSync SQLite database.
+     */
+    applyTransaction(transaction: Transaction<any>): Promise<void>;
+    protected handleInsert(mutation: PendingMutation<any>, context: LockContext, waitForCompletion?: boolean): Promise<PendingOperation | null>;
+    protected handleUpdate(mutation: PendingMutation<any>, context: LockContext, waitForCompletion?: boolean): Promise<PendingOperation | null>;
+    protected handleDelete(mutation: PendingMutation<any>, context: LockContext, waitForCompletion?: boolean): Promise<PendingOperation | null>;
+    /**
+     * Helper function which wraps a persistence operation by:
+     * - Fetching the mutation's collection's SQLite table details
+     * - Executing the mutation
+     * - Returning the last pending diff operation if required
+     */
+    protected handleOperationWithCompletion(mutation: PendingMutation<any>, context: LockContext, waitForCompletion: boolean, handler: (tableName: string, mutation: PendingMutation<any>, serializeValue: (value: any) => Record<string, unknown>) => Promise<void>): Promise<PendingOperation | null>;
+}

package/dist/cjs/definitions.cjs

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const DEFAULT_BATCH_SIZE = 1e3;
+exports.DEFAULT_BATCH_SIZE = DEFAULT_BATCH_SIZE;
+//# sourceMappingURL=definitions.cjs.map

package/dist/cjs/definitions.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.cjs","sources":["../../src/definitions.ts"],"sourcesContent":["import type { AbstractPowerSyncDatabase, Table } from \"@powersync/common\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\nimport type {\n  BaseCollectionConfig,\n  CollectionConfig,\n  InferSchemaOutput,\n} from \"@tanstack/db\"\nimport type {\n  AnyTableColumnType,\n  ExtractedTable,\n  OptionalExtractedTable,\n  PowerSyncRecord,\n} from \"./helpers\"\n\n/**\n * Small helper which determines the output type if:\n * - Standard SQLite types are to be used OR\n * - If the provided schema should be used.\n */\nexport type InferPowerSyncOutputType<\n  TTable extends Table = Table,\n  TSchema extends StandardSchemaV1<PowerSyncRecord> = never,\n> = TSchema extends never ? ExtractedTable<TTable> : InferSchemaOutput<TSchema>\n\n/**\n * A mapping type for custom serialization of object properties to SQLite-compatible values.\n *\n * This type allows you to override, for keys in the input object (`TOutput`), a function that transforms\n * the value to the corresponding SQLite type (`TSQLite`). Keys not specified will use the default SQLite serialization.\n *\n * ## Generics\n * - `TOutput`: The input object type, representing the row data to be serialized.\n * - `TSQLite`: The target SQLite-compatible type for each property, typically inferred from the table schema.\n *\n * ## Usage\n * Use this type to define a map of serialization functions for specific keys when you need custom handling\n * (e.g., converting complex objects, formatting dates, or handling enums).\n *\n * Example:\n * ```ts\n * const serializer: CustomSQLiteSerializer<MyRowType, MySQLiteType> = {\n *   createdAt: (date) => date.toISOString(),\n *   status: (status) => status ? 1 : 0,\n *   meta: (meta) => JSON.stringify(meta),\n * };\n * ```\n *\n * ## Behavior\n * - Each key maps to a function that receives the value and returns the SQLite-compatible value.\n * - Used by `serializeForSQLite` to override default serialization for specific columns.\n */\nexport type CustomSQLiteSerializer<\n  TOutput extends Record<string, unknown>,\n  TSQLite extends Record<string, unknown>,\n> = Partial<{\n  [Key in keyof TOutput]: (\n    value: TOutput[Key]\n  ) => Key extends keyof TSQLite ? TSQLite[Key] : never\n}>\n\nexport type SerializerConfig<\n  TOutput extends Record<string, unknown>,\n  TSQLite extends Record<string, unknown>,\n> = {\n  /**\n   * Optional partial serializer object for customizing how individual columns are serialized for SQLite.\n   *\n   * This should be a partial map of column keys to serialization functions, following the\n   * {@link CustomSQLiteSerializer} type. Each function receives the column value and returns a value\n   * compatible with SQLite storage.\n   *\n   * If not provided for a column, the default behavior is used:\n   *   - `TEXT`: Strings are stored as-is; Dates are converted to ISO strings; other types are JSON-stringified.\n   *   - `INTEGER`/`REAL`: Numbers are stored as-is; booleans are mapped to 1/0.\n   *\n   * Use this option to override serialization for specific columns, such as formatting dates, handling enums,\n   * or serializing complex objects.\n   *\n   * Example:\n   * ```typescript\n   * serializer: {\n   *   createdAt: (date) => date.getTime(), // Store as timestamp\n   *   meta: (meta) => JSON.stringify(meta), // Custom object serialization\n   * }\n   * ```\n   */\n  serializer?: CustomSQLiteSerializer<TOutput, TSQLite>\n\n  /**\n   * Application logic should ensure that incoming synced data is always valid.\n   * Failing to deserialize and apply incoming changes results in data inconsistency - which is a fatal error.\n   * Use this callback to react to deserialization errors.\n   */\n  onDeserializationError: (error: StandardSchemaV1.FailureResult) => void\n}\n\n/**\n * Config for when TInput and TOutput are both the SQLite types.\n */\nexport type ConfigWithSQLiteTypes = {}\n\n/**\n * Config where TInput is the SQLite types while TOutput can be defined by TSchema.\n * We can use the same schema to validate TInput and incoming SQLite changes.\n */\nexport type ConfigWithSQLiteInputType<\n  TTable extends Table,\n  TSchema extends StandardSchemaV1<\n    // TInput is the SQLite types.\n    OptionalExtractedTable<TTable>,\n    AnyTableColumnType<TTable>\n  >,\n> = SerializerConfig<\n  StandardSchemaV1.InferOutput<TSchema>,\n  ExtractedTable<TTable>\n> & {\n  schema: TSchema\n}\n\n/**\n * Config where TInput and TOutput have arbitrarily typed values.\n * The keys of the types need to equal the SQLite types.\n * Since TInput is not the SQLite types, we require a schema in order to deserialize incoming SQLite updates. The schema should validate from SQLite to TOutput.\n */\nexport type ConfigWithArbitraryCollectionTypes<\n  TTable extends Table,\n  TSchema extends StandardSchemaV1<\n    // The input and output must have the same keys, the value types can be arbitrary\n    AnyTableColumnType<TTable>,\n    AnyTableColumnType<TTable>\n  >,\n> = SerializerConfig<\n  StandardSchemaV1.InferOutput<TSchema>,\n  ExtractedTable<TTable>\n> & {\n  schema: TSchema\n  /**\n   * Schema for deserializing and validating input data from the sync stream.\n   *\n   * This schema defines how to transform and validate data coming from SQLite types (as stored in the database)\n   * into the desired output types (`TOutput`) expected by your application or validation logic.\n   *\n   * The generic parameters allow for arbitrary input and output types, so you can specify custom conversion rules\n   * for each column. This is especially useful when your application expects richer types (e.g., Date, enums, objects)\n   * than what SQLite natively supports.\n   *\n   * Use this to ensure that incoming data from the sync stream is properly converted and validated before use.\n   *\n   * Example:\n   * ```typescript\n   * deserializationSchema: z.object({\n   *   createdAt: z.preprocess((val) => new Date(val as string), z.date()),\n   *   meta: z.preprocess((val) => JSON.parse(val as string), z.object({ ... })),\n   * })\n   * ```\n   *\n   * This enables robust type safety and validation for incoming data, bridging the gap between SQLite storage\n   * and your application's expected types.\n   */\n  deserializationSchema: StandardSchemaV1<\n    ExtractedTable<TTable>,\n    StandardSchemaV1.InferOutput<TSchema>\n  >\n}\nexport type BasePowerSyncCollectionConfig<\n  TTable extends Table = Table,\n  TSchema extends StandardSchemaV1 = never,\n> = Omit<\n  BaseCollectionConfig<ExtractedTable<TTable>, string, TSchema>,\n  `onInsert` | `onUpdate` | `onDelete` | `getKey`\n> & {\n  /** The PowerSync schema Table definition */\n  table: TTable\n  /** The PowerSync database instance */\n  database: AbstractPowerSyncDatabase\n  /**\n   * The maximum number of documents to read from the SQLite table\n   * in a single batch during the initial sync between PowerSync and the\n   * in-memory TanStack DB collection.\n   *\n   * @remarks\n   * - Defaults to {@link DEFAULT_BATCH_SIZE} if not specified.\n   * - Larger values reduce the number of round trips to the storage\n   *   engine but increase memory usage per batch.\n   * - Smaller values may lower memory usage and allow earlier\n   *   streaming of initial results, at the cost of more query calls.\n   */\n  syncBatchSize?: number\n}\n\n/**\n * Configuration interface for PowerSync collection options.\n * @template TTable - The PowerSync table schema definition\n * @template TSchema - The validation schema type\n */\n/**\n * Configuration options for creating a PowerSync collection.\n *\n * @example\n * ```typescript\n * const APP_SCHEMA = new Schema({\n *   documents: new Table({\n *     name: column.text,\n *   }),\n * })\n *\n * const db = new PowerSyncDatabase({\n *   database: {\n *     dbFilename: \"test.sqlite\",\n *   },\n *   schema: APP_SCHEMA,\n * })\n *\n * const collection = createCollection(\n *   powerSyncCollectionOptions({\n *     database: db,\n *     table: APP_SCHEMA.props.documents\n *   })\n * )\n * ```\n */\nexport type PowerSyncCollectionConfig<\n  TTable extends Table = Table,\n  TSchema extends StandardSchemaV1<any> = never,\n> = BasePowerSyncCollectionConfig<TTable, TSchema> &\n  (\n    | ConfigWithSQLiteTypes\n    | ConfigWithSQLiteInputType<TTable, TSchema>\n    | ConfigWithArbitraryCollectionTypes<TTable, TSchema>\n  )\n\n/**\n * Metadata for the PowerSync Collection.\n */\nexport type PowerSyncCollectionMeta<TTable extends Table = Table> = {\n  /**\n   * The SQLite table representing the collection.\n   */\n  tableName: string\n  /**\n   * The internal table used to track diffs for the collection.\n   */\n  trackedTableName: string\n\n  /**\n   * Serializes a collection value to the SQLite type\n   */\n  serializeValue: (value: any) => ExtractedTable<TTable>\n}\n\n/**\n * A CollectionConfig which includes utilities for PowerSync.\n */\nexport type EnhancedPowerSyncCollectionConfig<\n  TTable extends Table,\n  OutputType extends Record<string, unknown> = Record<string, unknown>,\n  TSchema extends StandardSchemaV1 = never,\n> = CollectionConfig<OutputType, string, TSchema> & {\n  id?: string\n  utils: PowerSyncCollectionUtils<TTable>\n  schema?: TSchema\n}\n\n/**\n * Collection-level utilities for PowerSync.\n */\nexport type PowerSyncCollectionUtils<TTable extends Table = Table> = {\n  getMeta: () => PowerSyncCollectionMeta<TTable>\n}\n\n/**\n * Default value for {@link PowerSyncCollectionConfig#syncBatchSize}.\n */\nexport const DEFAULT_BATCH_SIZE = 1000\n"],"names":[],"mappings":";;AAiRO,MAAM,qBAAqB;;"}

package/dist/cjs/definitions.d.cts

@@ -0,0 +1,200 @@
+import { AbstractPowerSyncDatabase, Table } from '@powersync/common';
+import { StandardSchemaV1 } from '@standard-schema/spec';
+import { BaseCollectionConfig, CollectionConfig, InferSchemaOutput } from '@tanstack/db';
+import { AnyTableColumnType, ExtractedTable, OptionalExtractedTable, PowerSyncRecord } from './helpers.cjs';
+/**
+ * Small helper which determines the output type if:
+ * - Standard SQLite types are to be used OR
+ * - If the provided schema should be used.
+ */
+export type InferPowerSyncOutputType<TTable extends Table = Table, TSchema extends StandardSchemaV1<PowerSyncRecord> = never> = TSchema extends never ? ExtractedTable<TTable> : InferSchemaOutput<TSchema>;
+/**
+ * A mapping type for custom serialization of object properties to SQLite-compatible values.
+ *
+ * This type allows you to override, for keys in the input object (`TOutput`), a function that transforms
+ * the value to the corresponding SQLite type (`TSQLite`). Keys not specified will use the default SQLite serialization.
+ *
+ * ## Generics
+ * - `TOutput`: The input object type, representing the row data to be serialized.
+ * - `TSQLite`: The target SQLite-compatible type for each property, typically inferred from the table schema.
+ *
+ * ## Usage
+ * Use this type to define a map of serialization functions for specific keys when you need custom handling
+ * (e.g., converting complex objects, formatting dates, or handling enums).
+ *
+ * Example:
+ * ```ts
+ * const serializer: CustomSQLiteSerializer<MyRowType, MySQLiteType> = {
+ *   createdAt: (date) => date.toISOString(),
+ *   status: (status) => status ? 1 : 0,
+ *   meta: (meta) => JSON.stringify(meta),
+ * };
+ * ```
+ *
+ * ## Behavior
+ * - Each key maps to a function that receives the value and returns the SQLite-compatible value.
+ * - Used by `serializeForSQLite` to override default serialization for specific columns.
+ */
+export type CustomSQLiteSerializer<TOutput extends Record<string, unknown>, TSQLite extends Record<string, unknown>> = Partial<{
+    [Key in keyof TOutput]: (value: TOutput[Key]) => Key extends keyof TSQLite ? TSQLite[Key] : never;
+}>;
+export type SerializerConfig<TOutput extends Record<string, unknown>, TSQLite extends Record<string, unknown>> = {
+    /**
+     * Optional partial serializer object for customizing how individual columns are serialized for SQLite.
+     *
+     * This should be a partial map of column keys to serialization functions, following the
+     * {@link CustomSQLiteSerializer} type. Each function receives the column value and returns a value
+     * compatible with SQLite storage.
+     *
+     * If not provided for a column, the default behavior is used:
+     *   - `TEXT`: Strings are stored as-is; Dates are converted to ISO strings; other types are JSON-stringified.
+     *   - `INTEGER`/`REAL`: Numbers are stored as-is; booleans are mapped to 1/0.
+     *
+     * Use this option to override serialization for specific columns, such as formatting dates, handling enums,
+     * or serializing complex objects.
+     *
+     * Example:
+     * ```typescript
+     * serializer: {
+     *   createdAt: (date) => date.getTime(), // Store as timestamp
+     *   meta: (meta) => JSON.stringify(meta), // Custom object serialization
+     * }
+     * ```
+     */
+    serializer?: CustomSQLiteSerializer<TOutput, TSQLite>;
+    /**
+     * Application logic should ensure that incoming synced data is always valid.
+     * Failing to deserialize and apply incoming changes results in data inconsistency - which is a fatal error.
+     * Use this callback to react to deserialization errors.
+     */
+    onDeserializationError: (error: StandardSchemaV1.FailureResult) => void;
+};
+/**
+ * Config for when TInput and TOutput are both the SQLite types.
+ */
+export type ConfigWithSQLiteTypes = {};
+/**
+ * Config where TInput is the SQLite types while TOutput can be defined by TSchema.
+ * We can use the same schema to validate TInput and incoming SQLite changes.
+ */
+export type ConfigWithSQLiteInputType<TTable extends Table, TSchema extends StandardSchemaV1<OptionalExtractedTable<TTable>, AnyTableColumnType<TTable>>> = SerializerConfig<StandardSchemaV1.InferOutput<TSchema>, ExtractedTable<TTable>> & {
+    schema: TSchema;
+};
+/**
+ * Config where TInput and TOutput have arbitrarily typed values.
+ * The keys of the types need to equal the SQLite types.
+ * Since TInput is not the SQLite types, we require a schema in order to deserialize incoming SQLite updates. The schema should validate from SQLite to TOutput.
+ */
+export type ConfigWithArbitraryCollectionTypes<TTable extends Table, TSchema extends StandardSchemaV1<AnyTableColumnType<TTable>, AnyTableColumnType<TTable>>> = SerializerConfig<StandardSchemaV1.InferOutput<TSchema>, ExtractedTable<TTable>> & {
+    schema: TSchema;
+    /**
+     * Schema for deserializing and validating input data from the sync stream.
+     *
+     * This schema defines how to transform and validate data coming from SQLite types (as stored in the database)
+     * into the desired output types (`TOutput`) expected by your application or validation logic.
+     *
+     * The generic parameters allow for arbitrary input and output types, so you can specify custom conversion rules
+     * for each column. This is especially useful when your application expects richer types (e.g., Date, enums, objects)
+     * than what SQLite natively supports.
+     *
+     * Use this to ensure that incoming data from the sync stream is properly converted and validated before use.
+     *
+     * Example:
+     * ```typescript
+     * deserializationSchema: z.object({
+     *   createdAt: z.preprocess((val) => new Date(val as string), z.date()),
+     *   meta: z.preprocess((val) => JSON.parse(val as string), z.object({ ... })),
+     * })
+     * ```
+     *
+     * This enables robust type safety and validation for incoming data, bridging the gap between SQLite storage
+     * and your application's expected types.
+     */
+    deserializationSchema: StandardSchemaV1<ExtractedTable<TTable>, StandardSchemaV1.InferOutput<TSchema>>;
+};
+export type BasePowerSyncCollectionConfig<TTable extends Table = Table, TSchema extends StandardSchemaV1 = never> = Omit<BaseCollectionConfig<ExtractedTable<TTable>, string, TSchema>, `onInsert` | `onUpdate` | `onDelete` | `getKey`> & {
+    /** The PowerSync schema Table definition */
+    table: TTable;
+    /** The PowerSync database instance */
+    database: AbstractPowerSyncDatabase;
+    /**
+     * The maximum number of documents to read from the SQLite table
+     * in a single batch during the initial sync between PowerSync and the
+     * in-memory TanStack DB collection.
+     *
+     * @remarks
+     * - Defaults to {@link DEFAULT_BATCH_SIZE} if not specified.
+     * - Larger values reduce the number of round trips to the storage
+     *   engine but increase memory usage per batch.
+     * - Smaller values may lower memory usage and allow earlier
+     *   streaming of initial results, at the cost of more query calls.
+     */
+    syncBatchSize?: number;
+};
+/**
+ * Configuration interface for PowerSync collection options.
+ * @template TTable - The PowerSync table schema definition
+ * @template TSchema - The validation schema type
+ */
+/**
+ * Configuration options for creating a PowerSync collection.
+ *
+ * @example
+ * ```typescript
+ * const APP_SCHEMA = new Schema({
+ *   documents: new Table({
+ *     name: column.text,
+ *   }),
+ * })
+ *
+ * const db = new PowerSyncDatabase({
+ *   database: {
+ *     dbFilename: "test.sqlite",
+ *   },
+ *   schema: APP_SCHEMA,
+ * })
+ *
+ * const collection = createCollection(
+ *   powerSyncCollectionOptions({
+ *     database: db,
+ *     table: APP_SCHEMA.props.documents
+ *   })
+ * )
+ * ```
+ */
+export type PowerSyncCollectionConfig<TTable extends Table = Table, TSchema extends StandardSchemaV1<any> = never> = BasePowerSyncCollectionConfig<TTable, TSchema> & (ConfigWithSQLiteTypes | ConfigWithSQLiteInputType<TTable, TSchema> | ConfigWithArbitraryCollectionTypes<TTable, TSchema>);
+/**
+ * Metadata for the PowerSync Collection.
+ */
+export type PowerSyncCollectionMeta<TTable extends Table = Table> = {
+    /**
+     * The SQLite table representing the collection.
+     */
+    tableName: string;
+    /**
+     * The internal table used to track diffs for the collection.
+     */
+    trackedTableName: string;
+    /**
+     * Serializes a collection value to the SQLite type
+     */
+    serializeValue: (value: any) => ExtractedTable<TTable>;
+};
+/**
+ * A CollectionConfig which includes utilities for PowerSync.
+ */
+export type EnhancedPowerSyncCollectionConfig<TTable extends Table, OutputType extends Record<string, unknown> = Record<string, unknown>, TSchema extends StandardSchemaV1 = never> = CollectionConfig<OutputType, string, TSchema> & {
+    id?: string;
+    utils: PowerSyncCollectionUtils<TTable>;
+    schema?: TSchema;
+};
+/**
+ * Collection-level utilities for PowerSync.
+ */
+export type PowerSyncCollectionUtils<TTable extends Table = Table> = {
+    getMeta: () => PowerSyncCollectionMeta<TTable>;
+};
+/**
+ * Default value for {@link PowerSyncCollectionConfig#syncBatchSize}.
+ */
+export declare const DEFAULT_BATCH_SIZE = 1000;

package/dist/cjs/helpers.cjs

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const common = require("@powersync/common");
+function asPowerSyncRecord(record) {
+  if (typeof record.id !== `string`) {
+    throw new Error(`Record must have a string id field`);
+  }
+  return record;
+}
+function mapOperation(operation) {
+  switch (operation) {
+    case common.DiffTriggerOperation.INSERT:
+      return `insert`;
+    case common.DiffTriggerOperation.UPDATE:
+      return `update`;
+    case common.DiffTriggerOperation.DELETE:
+      return `delete`;
+  }
+}
+function mapOperationToPowerSync(operation) {
+  switch (operation) {
+    case `insert`:
+      return common.DiffTriggerOperation.INSERT;
+    case `update`:
+      return common.DiffTriggerOperation.UPDATE;
+    case `delete`:
+      return common.DiffTriggerOperation.DELETE;
+    default:
+      throw new Error(`Unknown operation ${operation} received`);
+  }
+}
+exports.asPowerSyncRecord = asPowerSyncRecord;
+exports.mapOperation = mapOperation;
+exports.mapOperationToPowerSync = mapOperationToPowerSync;
+//# sourceMappingURL=helpers.cjs.map

package/dist/cjs/helpers.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.cjs","sources":["../../src/helpers.ts"],"sourcesContent":["import { DiffTriggerOperation } from \"@powersync/common\"\nimport type {\n  BaseColumnType,\n  ExtractColumnValueType,\n  Table,\n} from \"@powersync/common\"\n\n/**\n * All PowerSync table records include a UUID `id` column.\n */\nexport type PowerSyncRecord = {\n  id: string\n  [key: string]: unknown\n}\n\n/**\n * Utility type: If T includes null, also allow undefined (to support optional fields in insert/update operations).\n * PowerSync records are typically typed as `string | null`, where insert\n * and update operations may also allow not specifying a value at all (optional).\n */\ntype WithUndefinedIfNull<T> = null extends T ? T | undefined : T\ntype OptionalIfUndefined<T> = {\n  [K in keyof T as undefined extends T[K] ? K : never]?: T[K]\n} & {\n  [K in keyof T as undefined extends T[K] ? never : K]: T[K]\n}\n\n/**\n * Provides the base column types for a table. This excludes the `id` column.\n */\nexport type ExtractedTableColumns<TTable extends Table> = {\n  [K in keyof TTable[`columnMap`]]: ExtractColumnValueType<\n    TTable[`columnMap`][K]\n  >\n}\n/**\n * Utility type that extracts the typed structure of a table based on its column definitions.\n * Maps each column to its corresponding TypeScript type using ExtractColumnValueType.\n *\n * @template TTable - The PowerSync table definition\n * @example\n * ```typescript\n * const table = new Table({\n *   name: column.text,\n *   age: column.integer\n * })\n * type TableType = ExtractedTable<typeof table>\n * // Results in: { id: string, name: string | null, age: number | null }\n * ```\n */\nexport type ExtractedTable<TTable extends Table> =\n  ExtractedTableColumns<TTable> & {\n    id: string\n  }\n\nexport type OptionalExtractedTable<TTable extends Table> = OptionalIfUndefined<{\n  [K in keyof TTable[`columnMap`]]: WithUndefinedIfNull<\n    ExtractColumnValueType<TTable[`columnMap`][K]>\n  >\n}> & {\n  id: string\n}\n\n/**\n * Maps the schema of TTable to a type which\n * requires the keys be equal, but the values can have any value type.\n */\nexport type AnyTableColumnType<TTable extends Table> = {\n  [K in keyof TTable[`columnMap`]]: any\n} & { id: string }\n\nexport function asPowerSyncRecord(record: any): PowerSyncRecord {\n  if (typeof record.id !== `string`) {\n    throw new Error(`Record must have a string id field`)\n  }\n  return record as PowerSyncRecord\n}\n\n//  Helper type to ensure the keys of TOutput match the Table columns\nexport type MapBaseColumnType<TOutput> = {\n  [Key in keyof TOutput]: BaseColumnType<any>\n}\n\n/**\n * Maps {@link DiffTriggerOperation} to TanstackDB operations\n */\nexport function mapOperation(operation: DiffTriggerOperation) {\n  switch (operation) {\n    case DiffTriggerOperation.INSERT:\n      return `insert`\n    case DiffTriggerOperation.UPDATE:\n      return `update`\n    case DiffTriggerOperation.DELETE:\n      return `delete`\n  }\n}\n\n/**\n * Maps TanstackDB operations to  {@link DiffTriggerOperation}\n */\nexport function mapOperationToPowerSync(operation: string) {\n  switch (operation) {\n    case `insert`:\n      return DiffTriggerOperation.INSERT\n    case `update`:\n      return DiffTriggerOperation.UPDATE\n    case `delete`:\n      return DiffTriggerOperation.DELETE\n    default:\n      throw new Error(`Unknown operation ${operation} received`)\n  }\n}\n"],"names":["DiffTriggerOperation"],"mappings":";;;AAuEO,SAAS,kBAAkB,QAA8B;AAC9D,MAAI,OAAO,OAAO,OAAO,UAAU;AACjC,UAAM,IAAI,MAAM,oCAAoC;AAAA,EACtD;AACA,SAAO;AACT;AAUO,SAAS,aAAa,WAAiC;AAC5D,UAAQ,WAAA;AAAA,IACN,KAAKA,OAAAA,qBAAqB;AACxB,aAAO;AAAA,IACT,KAAKA,OAAAA,qBAAqB;AACxB,aAAO;AAAA,IACT,KAAKA,OAAAA,qBAAqB;AACxB,aAAO;AAAA,EAAA;AAEb;AAKO,SAAS,wBAAwB,WAAmB;AACzD,UAAQ,WAAA;AAAA,IACN,KAAK;AACH,aAAOA,OAAAA,qBAAqB;AAAA,IAC9B,KAAK;AACH,aAAOA,OAAAA,qBAAqB;AAAA,IAC9B,KAAK;AACH,aAAOA,OAAAA,qBAAqB;AAAA,IAC9B;AACE,YAAM,IAAI,MAAM,qBAAqB,SAAS,WAAW;AAAA,EAAA;AAE/D;;;;"}