@tanstack/db 0.0.4 → 0.0.6

package/src/types.ts

@@ -1,3 +1,4 @@
+import type { IStreamBuilder } from "@electric-sql/d2ts"
 import type { Collection } from "./collection"
 import type { StandardSchemaV1 } from "@standard-schema/spec"
 import type { Transaction } from "./transactions"
@@ -13,7 +14,7 @@ export interface PendingMutation<T extends object = Record<string, unknown>> {
   original: Record<string, unknown>
   modified: Record<string, unknown>
   changes: Record<string, unknown>
-  key: string
+  key: any
   type: OperationType
   metadata: unknown
   syncMetadata: Record<string, unknown>
@@ -31,6 +32,16 @@ export type MutationFnParams = {
 
 export type MutationFn = (params: MutationFnParams) => Promise<any>
 
+/**
+ * Utility type for a Transaction with at least one mutation
+ * This is used internally by the Transaction.commit method
+ */
+export type TransactionWithMutations<
+  T extends object = Record<string, unknown>,
+> = Transaction & {
+  mutations: [PendingMutation<T>, ...Array<PendingMutation<T>>]
+}
+
 export interface TransactionConfig {
   /** Unique identifier for the transaction */
   id?: string
@@ -51,7 +62,7 @@ type Value<TExtensions = never> =
   | null
   | TExtensions
   | Array<Value<TExtensions>>
-  | { [key: string]: Value<TExtensions> }
+  | { [key: string | number | symbol]: Value<TExtensions> }
 
 export type Row<TExtensions = never> = Record<string, Value<TExtensions>>
 
@@ -61,19 +72,19 @@ export interface SyncConfig<T extends object = Record<string, unknown>> {
   sync: (params: {
     collection: Collection<T>
     begin: () => void
-    write: (message: ChangeMessage<T>) => void
+    write: (message: Omit<ChangeMessage<T>, `key`>) => void
     commit: () => void
   }) => void
 
   /**
    * Get the sync metadata for insert operations
-   * @returns Record containing primaryKey and relation information
+   * @returns Record containing relation information
    */
   getSyncMetadata?: () => Record<string, unknown>
 }
 
 export interface ChangeMessage<T extends object = Record<string, unknown>> {
-  key: string
+  key: any
   value: T
   previousValue?: T
   type: OperationType
@@ -110,16 +121,74 @@ export interface OperationConfig {
 }
 
 export interface InsertConfig {
-  key?: string | Array<string | undefined>
   metadata?: Record<string, unknown>
 }
 
 export interface CollectionConfig<T extends object = Record<string, unknown>> {
-  id: string
+  // If an id isn't passed in, a UUID will be
+  // generated for it.
+  id?: string
   sync: SyncConfig<T>
   schema?: StandardSchema<T>
+  /**
+   * Function to extract the ID from an object
+   * This is required for update/delete operations which now only accept IDs
+   * @param item The item to extract the ID from
+   * @returns The ID string for the item
+   * @example
+   * // For a collection with a 'uuid' field as the primary key
+   * getId: (item) => item.uuid
+   */
+  getId: (item: T) => any
+  /**
+   * Optional asynchronous handler function called before an insert operation
+   * @param params Object containing transaction and mutation information
+   * @returns Promise resolving to any value
+   */
+  onInsert?: MutationFn
+  /**
+   * Optional asynchronous handler function called before an update operation
+   * @param params Object containing transaction and mutation information
+   * @returns Promise resolving to any value
+   */
+  onUpdate?: MutationFn
+  /**
+   * Optional asynchronous handler function called before a delete operation
+   * @param params Object containing transaction and mutation information
+   * @returns Promise resolving to any value
+   */
+  onDelete?: MutationFn
 }
 
 export type ChangesPayload<T extends object = Record<string, unknown>> = Array<
   ChangeMessage<T>
 >
+
+/**
+ * An input row from a collection
+ */
+export type InputRow = [unknown, Record<string, unknown>]
+
+/**
+ * A keyed stream is a stream of rows
+ * This is used as the inputs from a collection to a query
+ */
+export type KeyedStream = IStreamBuilder<InputRow>
+
+/**
+ * A namespaced row is a row withing a pipeline that had each table wrapped in its alias
+ */
+export type NamespacedRow = Record<string, Record<string, unknown>>
+
+/**
+ * A keyed namespaced row is a row with a key and a namespaced row
+ * This is the main representation of a row in a query pipeline
+ */
+export type KeyedNamespacedRow = [unknown, NamespacedRow]
+
+/**
+ * A namespaced and keyed stream is a stream of rows
+ * This is used throughout a query pipeline and as the output from a query without
+ * a `select` clause.
+ */
+export type NamespacedAndKeyedStream = IStreamBuilder<KeyedNamespacedRow>

package/dist/cjs/query/key-by.cjs

@@ -1,43 +0,0 @@
-"use strict";
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const d2ts = require("@electric-sql/d2ts");
-function processKeyBy(resultPipeline, query) {
-  if (!query.keyBy) {
-    return resultPipeline;
-  }
-  const keyByParam = query.keyBy;
-  resultPipeline = resultPipeline.pipe(
-    d2ts.keyBy((row) => {
-      if (Array.isArray(keyByParam)) {
-        const keyValues = {};
-        for (const keyColumn of keyByParam) {
-          const columnName = keyColumn.startsWith(`@`) ? keyColumn.substring(1) : keyColumn;
-          if (columnName in row) {
-            keyValues[columnName] = row[columnName];
-          } else {
-            throw new Error(
-              `Key column "${columnName}" not found in result set. Make sure it's included in the select clause.`
-            );
-          }
-        }
-        return JSON.stringify(keyValues);
-      } else {
-        const columnName = keyByParam.startsWith(`@`) ? keyByParam.substring(1) : keyByParam;
-        if (!(columnName in row)) {
-          throw new Error(
-            `Key column "${columnName}" not found in result set. Make sure it's included in the select clause.`
-          );
-        }
-        const keyValue = row[columnName];
-        if (typeof keyValue === `string` || typeof keyValue === `number`) {
-          return keyValue;
-        } else {
-          return JSON.stringify(keyValue);
-        }
-      }
-    })
-  );
-  return resultPipeline;
-}
-exports.processKeyBy = processKeyBy;
-//# sourceMappingURL=key-by.cjs.map

package/dist/cjs/query/key-by.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"key-by.cjs","sources":["../../../src/query/key-by.ts"],"sourcesContent":["import { keyBy } from \"@electric-sql/d2ts\"\nimport type { IStreamBuilder } from \"@electric-sql/d2ts\"\nimport type { Query } from \"./schema\"\n\nexport function processKeyBy(\n  resultPipeline: IStreamBuilder<\n    Record<string, unknown> | [string | number, Record<string, unknown>]\n  >,\n  query: Query\n) {\n  if (!query.keyBy) {\n    return resultPipeline\n  }\n  const keyByParam = query.keyBy\n\n  resultPipeline = resultPipeline.pipe(\n    keyBy((row: Record<string, unknown>) => {\n      if (Array.isArray(keyByParam)) {\n        // Multiple columns - extract values and JSON stringify\n        const keyValues: Record<string, unknown> = {}\n        for (const keyColumn of keyByParam) {\n          // Remove @ prefix if present\n          const columnName = (keyColumn as string).startsWith(`@`)\n            ? (keyColumn as string).substring(1)\n            : (keyColumn as string)\n\n          if (columnName in row) {\n            keyValues[columnName] = row[columnName]\n          } else {\n            throw new Error(\n              `Key column \"${columnName}\" not found in result set. Make sure it's included in the select clause.`\n            )\n          }\n        }\n        return JSON.stringify(keyValues)\n      } else {\n        // Single column\n        // Remove @ prefix if present\n        const columnName = (keyByParam as string).startsWith(`@`)\n          ? (keyByParam as string).substring(1)\n          : (keyByParam as string)\n\n        if (!(columnName in row)) {\n          throw new Error(\n            `Key column \"${columnName}\" not found in result set. Make sure it's included in the select clause.`\n          )\n        }\n\n        const keyValue = row[columnName]\n        // Use the value directly if it's a string or number, otherwise JSON stringify\n        if (typeof keyValue === `string` || typeof keyValue === `number`) {\n          return keyValue\n        } else {\n          return JSON.stringify(keyValue)\n        }\n      }\n    })\n  )\n\n  return resultPipeline\n}\n"],"names":["keyBy"],"mappings":";;;AAIgB,SAAA,aACd,gBAGA,OACA;AACI,MAAA,CAAC,MAAM,OAAO;AACT,WAAA;AAAA,EAAA;AAET,QAAM,aAAa,MAAM;AAEzB,mBAAiB,eAAe;AAAA,IAC9BA,KAAA,MAAM,CAAC,QAAiC;AAClC,UAAA,MAAM,QAAQ,UAAU,GAAG;AAE7B,cAAM,YAAqC,CAAC;AAC5C,mBAAW,aAAa,YAAY;AAE5B,gBAAA,aAAc,UAAqB,WAAW,GAAG,IAClD,UAAqB,UAAU,CAAC,IAChC;AAEL,cAAI,cAAc,KAAK;AACX,sBAAA,UAAU,IAAI,IAAI,UAAU;AAAA,UAAA,OACjC;AACL,kBAAM,IAAI;AAAA,cACR,eAAe,UAAU;AAAA,YAC3B;AAAA,UAAA;AAAA,QACF;AAEK,eAAA,KAAK,UAAU,SAAS;AAAA,MAAA,OAC1B;AAGC,cAAA,aAAc,WAAsB,WAAW,GAAG,IACnD,WAAsB,UAAU,CAAC,IACjC;AAED,YAAA,EAAE,cAAc,MAAM;AACxB,gBAAM,IAAI;AAAA,YACR,eAAe,UAAU;AAAA,UAC3B;AAAA,QAAA;AAGI,cAAA,WAAW,IAAI,UAAU;AAE/B,YAAI,OAAO,aAAa,YAAY,OAAO,aAAa,UAAU;AACzD,iBAAA;AAAA,QAAA,OACF;AACE,iBAAA,KAAK,UAAU,QAAQ;AAAA,QAAA;AAAA,MAChC;AAAA,IAEH,CAAA;AAAA,EACH;AAEO,SAAA;AACT;;"}

package/dist/cjs/query/key-by.d.cts

@@ -1,3 +0,0 @@
-import { IStreamBuilder } from '@electric-sql/d2ts';
-import { Query } from './schema.cjs';
-export declare function processKeyBy(resultPipeline: IStreamBuilder<Record<string, unknown> | [string | number, Record<string, unknown>]>, query: Query): IStreamBuilder<Record<string, unknown> | [string | number, Record<string, unknown>]>;

package/dist/esm/query/key-by.d.ts

@@ -1,3 +0,0 @@
-import { IStreamBuilder } from '@electric-sql/d2ts';
-import { Query } from './schema.js';
-export declare function processKeyBy(resultPipeline: IStreamBuilder<Record<string, unknown> | [string | number, Record<string, unknown>]>, query: Query): IStreamBuilder<Record<string, unknown> | [string | number, Record<string, unknown>]>;

package/dist/esm/query/key-by.js

@@ -1,43 +0,0 @@
-import { keyBy } from "@electric-sql/d2ts";
-function processKeyBy(resultPipeline, query) {
-  if (!query.keyBy) {
-    return resultPipeline;
-  }
-  const keyByParam = query.keyBy;
-  resultPipeline = resultPipeline.pipe(
-    keyBy((row) => {
-      if (Array.isArray(keyByParam)) {
-        const keyValues = {};
-        for (const keyColumn of keyByParam) {
-          const columnName = keyColumn.startsWith(`@`) ? keyColumn.substring(1) : keyColumn;
-          if (columnName in row) {
-            keyValues[columnName] = row[columnName];
-          } else {
-            throw new Error(
-              `Key column "${columnName}" not found in result set. Make sure it's included in the select clause.`
-            );
-          }
-        }
-        return JSON.stringify(keyValues);
-      } else {
-        const columnName = keyByParam.startsWith(`@`) ? keyByParam.substring(1) : keyByParam;
-        if (!(columnName in row)) {
-          throw new Error(
-            `Key column "${columnName}" not found in result set. Make sure it's included in the select clause.`
-          );
-        }
-        const keyValue = row[columnName];
-        if (typeof keyValue === `string` || typeof keyValue === `number`) {
-          return keyValue;
-        } else {
-          return JSON.stringify(keyValue);
-        }
-      }
-    })
-  );
-  return resultPipeline;
-}
-export {
-  processKeyBy
-};
-//# sourceMappingURL=key-by.js.map

package/dist/esm/query/key-by.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"key-by.js","sources":["../../../src/query/key-by.ts"],"sourcesContent":["import { keyBy } from \"@electric-sql/d2ts\"\nimport type { IStreamBuilder } from \"@electric-sql/d2ts\"\nimport type { Query } from \"./schema\"\n\nexport function processKeyBy(\n  resultPipeline: IStreamBuilder<\n    Record<string, unknown> | [string | number, Record<string, unknown>]\n  >,\n  query: Query\n) {\n  if (!query.keyBy) {\n    return resultPipeline\n  }\n  const keyByParam = query.keyBy\n\n  resultPipeline = resultPipeline.pipe(\n    keyBy((row: Record<string, unknown>) => {\n      if (Array.isArray(keyByParam)) {\n        // Multiple columns - extract values and JSON stringify\n        const keyValues: Record<string, unknown> = {}\n        for (const keyColumn of keyByParam) {\n          // Remove @ prefix if present\n          const columnName = (keyColumn as string).startsWith(`@`)\n            ? (keyColumn as string).substring(1)\n            : (keyColumn as string)\n\n          if (columnName in row) {\n            keyValues[columnName] = row[columnName]\n          } else {\n            throw new Error(\n              `Key column \"${columnName}\" not found in result set. Make sure it's included in the select clause.`\n            )\n          }\n        }\n        return JSON.stringify(keyValues)\n      } else {\n        // Single column\n        // Remove @ prefix if present\n        const columnName = (keyByParam as string).startsWith(`@`)\n          ? (keyByParam as string).substring(1)\n          : (keyByParam as string)\n\n        if (!(columnName in row)) {\n          throw new Error(\n            `Key column \"${columnName}\" not found in result set. Make sure it's included in the select clause.`\n          )\n        }\n\n        const keyValue = row[columnName]\n        // Use the value directly if it's a string or number, otherwise JSON stringify\n        if (typeof keyValue === `string` || typeof keyValue === `number`) {\n          return keyValue\n        } else {\n          return JSON.stringify(keyValue)\n        }\n      }\n    })\n  )\n\n  return resultPipeline\n}\n"],"names":[],"mappings":";AAIgB,SAAA,aACd,gBAGA,OACA;AACI,MAAA,CAAC,MAAM,OAAO;AACT,WAAA;AAAA,EAAA;AAET,QAAM,aAAa,MAAM;AAEzB,mBAAiB,eAAe;AAAA,IAC9B,MAAM,CAAC,QAAiC;AAClC,UAAA,MAAM,QAAQ,UAAU,GAAG;AAE7B,cAAM,YAAqC,CAAC;AAC5C,mBAAW,aAAa,YAAY;AAE5B,gBAAA,aAAc,UAAqB,WAAW,GAAG,IAClD,UAAqB,UAAU,CAAC,IAChC;AAEL,cAAI,cAAc,KAAK;AACX,sBAAA,UAAU,IAAI,IAAI,UAAU;AAAA,UAAA,OACjC;AACL,kBAAM,IAAI;AAAA,cACR,eAAe,UAAU;AAAA,YAC3B;AAAA,UAAA;AAAA,QACF;AAEK,eAAA,KAAK,UAAU,SAAS;AAAA,MAAA,OAC1B;AAGC,cAAA,aAAc,WAAsB,WAAW,GAAG,IACnD,WAAsB,UAAU,CAAC,IACjC;AAED,YAAA,EAAE,cAAc,MAAM;AACxB,gBAAM,IAAI;AAAA,YACR,eAAe,UAAU;AAAA,UAC3B;AAAA,QAAA;AAGI,cAAA,WAAW,IAAI,UAAU;AAE/B,YAAI,OAAO,aAAa,YAAY,OAAO,aAAa,UAAU;AACzD,iBAAA;AAAA,QAAA,OACF;AACE,iBAAA,KAAK,UAAU,QAAQ;AAAA,QAAA;AAAA,MAChC;AAAA,IAEH,CAAA;AAAA,EACH;AAEO,SAAA;AACT;"}

package/src/query/key-by.ts

@@ -1,61 +0,0 @@
-import { keyBy } from "@electric-sql/d2ts"
-import type { IStreamBuilder } from "@electric-sql/d2ts"
-import type { Query } from "./schema"
-
-export function processKeyBy(
-  resultPipeline: IStreamBuilder<
-    Record<string, unknown> | [string | number, Record<string, unknown>]
-  >,
-  query: Query
-) {
-  if (!query.keyBy) {
-    return resultPipeline
-  }
-  const keyByParam = query.keyBy
-
-  resultPipeline = resultPipeline.pipe(
-    keyBy((row: Record<string, unknown>) => {
-      if (Array.isArray(keyByParam)) {
-        // Multiple columns - extract values and JSON stringify
-        const keyValues: Record<string, unknown> = {}
-        for (const keyColumn of keyByParam) {
-          // Remove @ prefix if present
-          const columnName = (keyColumn as string).startsWith(`@`)
-            ? (keyColumn as string).substring(1)
-            : (keyColumn as string)
-
-          if (columnName in row) {
-            keyValues[columnName] = row[columnName]
-          } else {
-            throw new Error(
-              `Key column "${columnName}" not found in result set. Make sure it's included in the select clause.`
-            )
-          }
-        }
-        return JSON.stringify(keyValues)
-      } else {
-        // Single column
-        // Remove @ prefix if present
-        const columnName = (keyByParam as string).startsWith(`@`)
-          ? (keyByParam as string).substring(1)
-          : (keyByParam as string)
-
-        if (!(columnName in row)) {
-          throw new Error(
-            `Key column "${columnName}" not found in result set. Make sure it's included in the select clause.`
-          )
-        }
-
-        const keyValue = row[columnName]
-        // Use the value directly if it's a string or number, otherwise JSON stringify
-        if (typeof keyValue === `string` || typeof keyValue === `number`) {
-          return keyValue
-        } else {
-          return JSON.stringify(keyValue)
-        }
-      }
-    })
-  )
-
-  return resultPipeline
-}