@tanstack/db 0.0.6 → 0.0.8

package/dist/cjs/transactions.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"transactions.cjs","sources":["../../src/transactions.ts"],"sourcesContent":["import { createDeferred } from \"./deferred\"\nimport type { Deferred } from \"./deferred\"\nimport type {\n  PendingMutation,\n  TransactionConfig,\n  TransactionState,\n  TransactionWithMutations,\n} from \"./types\"\n\nfunction generateUUID() {\n  // Check if crypto.randomUUID is available (modern browsers and Node.js 15+)\n  if (\n    typeof crypto !== `undefined` &&\n    typeof crypto.randomUUID === `function`\n  ) {\n    return crypto.randomUUID()\n  }\n\n  // Fallback implementation for older environments\n  return `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`.replace(/[xy]/g, function (c) {\n    const r = (Math.random() * 16) | 0\n    const v = c === `x` ? r : (r & 0x3) | 0x8\n    return v.toString(16)\n  })\n}\n\nconst transactions: Array<Transaction> = []\nlet transactionStack: Array<Transaction> = []\n\nexport function createTransaction(config: TransactionConfig): Transaction {\n  if (typeof config.mutationFn === `undefined`) {\n    throw `mutationFn is required when creating a transaction`\n  }\n\n  let transactionId = config.id\n  if (!transactionId) {\n    transactionId = generateUUID()\n  }\n  const newTransaction = new Transaction({ ...config, id: transactionId })\n\n  transactions.push(newTransaction)\n\n  return newTransaction\n}\n\nexport function getActiveTransaction(): Transaction | undefined {\n  if (transactionStack.length > 0) {\n    return transactionStack.slice(-1)[0]\n  } else {\n    return undefined\n  }\n}\n\nfunction registerTransaction(tx: Transaction) {\n  transactionStack.push(tx)\n}\n\nfunction unregisterTransaction(tx: Transaction) {\n  transactionStack = transactionStack.filter((t) => t.id !== tx.id)\n}\n\nfunction removeFromPendingList(tx: Transaction) {\n  const index = transactions.findIndex((t) => t.id === tx.id)\n  if (index !== -1) {\n    transactions.splice(index, 1)\n  }\n}\n\nexport class Transaction {\n  public id: string\n  public state: TransactionState\n  public mutationFn\n  public mutations: Array<PendingMutation<any>>\n  public isPersisted: Deferred<Transaction>\n  public autoCommit: boolean\n  public createdAt: Date\n  public metadata: Record<string, unknown>\n  public error?: {\n    message: string\n    error: Error\n  }\n\n  constructor(config: TransactionConfig) {\n    this.id = config.id!\n    this.mutationFn = config.mutationFn\n    this.state = `pending`\n    this.mutations = []\n    this.isPersisted = createDeferred()\n    this.autoCommit = config.autoCommit ?? true\n    this.createdAt = new Date()\n    this.metadata = config.metadata ?? {}\n  }\n\n  setState(newState: TransactionState) {\n    this.state = newState\n\n    if (newState === `completed` || newState === `failed`) {\n      removeFromPendingList(this)\n    }\n  }\n\n  mutate(callback: () => void): Transaction {\n    if (this.state !== `pending`) {\n      throw `You can no longer call .mutate() as the transaction is no longer pending`\n    }\n\n    registerTransaction(this)\n    try {\n      callback()\n    } finally {\n      unregisterTransaction(this)\n    }\n\n    if (this.autoCommit) {\n      this.commit()\n    }\n\n    return this\n  }\n\n  applyMutations(mutations: Array<PendingMutation<any>>): void {\n    for (const newMutation of mutations) {\n      const existingIndex = this.mutations.findIndex(\n        (m) => m.key === newMutation.key\n      )\n\n      if (existingIndex >= 0) {\n        // Replace existing mutation\n        this.mutations[existingIndex] = newMutation\n      } else {\n        // Insert new mutation\n        this.mutations.push(newMutation)\n      }\n    }\n  }\n\n  rollback(config?: { isSecondaryRollback?: boolean }): Transaction {\n    const isSecondaryRollback = config?.isSecondaryRollback ?? false\n    if (this.state === `completed`) {\n      throw `You can no longer call .rollback() as the transaction is already completed`\n    }\n\n    this.setState(`failed`)\n\n    // See if there's any other transactions w/ mutations on the same ids\n    // and roll them back as well.\n    if (!isSecondaryRollback) {\n      const mutationIds = new Set()\n      this.mutations.forEach((m) => mutationIds.add(m.key))\n      for (const t of transactions) {\n        t.state === `pending` &&\n          t.mutations.some((m) => mutationIds.has(m.key)) &&\n          t.rollback({ isSecondaryRollback: true })\n      }\n    }\n\n    // Reject the promise\n    this.isPersisted.reject(this.error?.error)\n    this.touchCollection()\n\n    return this\n  }\n\n  // Tell collection that something has changed with the transaction\n  touchCollection(): void {\n    const hasCalled = new Set()\n    for (const mutation of this.mutations) {\n      if (!hasCalled.has(mutation.collection.id)) {\n        mutation.collection.transactions.setState((state) => state)\n        mutation.collection.commitPendingTransactions()\n        hasCalled.add(mutation.collection.id)\n      }\n    }\n  }\n\n  async commit(): Promise<Transaction> {\n    if (this.state !== `pending`) {\n      throw `You can no longer call .commit() as the transaction is no longer pending`\n    }\n\n    this.setState(`persisting`)\n\n    if (this.mutations.length === 0) {\n      this.setState(`completed`)\n\n      return this\n    }\n\n    // Run mutationFn\n    try {\n      // At this point we know there's at least one mutation\n      // Use type assertion to tell TypeScript about this guarantee\n      const transactionWithMutations =\n        this as unknown as TransactionWithMutations\n      await this.mutationFn({ transaction: transactionWithMutations })\n\n      this.setState(`completed`)\n      this.touchCollection()\n\n      this.isPersisted.resolve(this)\n    } catch (error) {\n      // Update transaction with error information\n      this.error = {\n        message: error instanceof Error ? error.message : String(error),\n        error: error instanceof Error ? error : new Error(String(error)),\n      }\n\n      // rollback the transaction\n      return this.rollback()\n    }\n\n    return this\n  }\n}\n"],"names":["createDeferred"],"mappings":"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"}
+{"version":3,"file":"transactions.cjs","sources":["../../src/transactions.ts"],"sourcesContent":["import { createDeferred } from \"./deferred\"\nimport type { Deferred } from \"./deferred\"\nimport type {\n  MutationFn,\n  PendingMutation,\n  TransactionConfig,\n  TransactionState,\n  TransactionWithMutations,\n} from \"./types\"\n\nfunction generateUUID() {\n  // Check if crypto.randomUUID is available (modern browsers and Node.js 15+)\n  if (\n    typeof crypto !== `undefined` &&\n    typeof crypto.randomUUID === `function`\n  ) {\n    return crypto.randomUUID()\n  }\n\n  // Fallback implementation for older environments\n  return `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`.replace(/[xy]/g, function (c) {\n    const r = (Math.random() * 16) | 0\n    const v = c === `x` ? r : (r & 0x3) | 0x8\n    return v.toString(16)\n  })\n}\n\nconst transactions: Array<Transaction<any>> = []\nlet transactionStack: Array<Transaction<any>> = []\n\nexport function createTransaction(config: TransactionConfig): Transaction {\n  if (typeof config.mutationFn === `undefined`) {\n    throw `mutationFn is required when creating a transaction`\n  }\n\n  let transactionId = config.id\n  if (!transactionId) {\n    transactionId = generateUUID()\n  }\n  const newTransaction = new Transaction({ ...config, id: transactionId })\n\n  transactions.push(newTransaction)\n\n  return newTransaction\n}\n\nexport function getActiveTransaction(): Transaction | undefined {\n  if (transactionStack.length > 0) {\n    return transactionStack.slice(-1)[0]\n  } else {\n    return undefined\n  }\n}\n\nfunction registerTransaction(tx: Transaction<any>) {\n  transactionStack.push(tx)\n}\n\nfunction unregisterTransaction(tx: Transaction<any>) {\n  transactionStack = transactionStack.filter((t) => t.id !== tx.id)\n}\n\nfunction removeFromPendingList(tx: Transaction<any>) {\n  const index = transactions.findIndex((t) => t.id === tx.id)\n  if (index !== -1) {\n    transactions.splice(index, 1)\n  }\n}\n\nexport class Transaction<T extends object = Record<string, unknown>> {\n  public id: string\n  public state: TransactionState\n  public mutationFn: MutationFn<T>\n  public mutations: Array<PendingMutation<T>>\n  public isPersisted: Deferred<Transaction<T>>\n  public autoCommit: boolean\n  public createdAt: Date\n  public metadata: Record<string, unknown>\n  public error?: {\n    message: string\n    error: Error\n  }\n\n  constructor(config: TransactionConfig<T>) {\n    this.id = config.id!\n    this.mutationFn = config.mutationFn\n    this.state = `pending`\n    this.mutations = []\n    this.isPersisted = createDeferred<Transaction<T>>()\n    this.autoCommit = config.autoCommit ?? true\n    this.createdAt = new Date()\n    this.metadata = config.metadata ?? {}\n  }\n\n  setState(newState: TransactionState) {\n    this.state = newState\n\n    if (newState === `completed` || newState === `failed`) {\n      removeFromPendingList(this)\n    }\n  }\n\n  mutate(callback: () => void): Transaction<T> {\n    if (this.state !== `pending`) {\n      throw `You can no longer call .mutate() as the transaction is no longer pending`\n    }\n\n    registerTransaction(this)\n    try {\n      callback()\n    } finally {\n      unregisterTransaction(this)\n    }\n\n    if (this.autoCommit) {\n      this.commit()\n    }\n\n    return this\n  }\n\n  applyMutations(mutations: Array<PendingMutation<any>>): void {\n    for (const newMutation of mutations) {\n      const existingIndex = this.mutations.findIndex(\n        (m) => m.globalKey === newMutation.globalKey\n      )\n\n      if (existingIndex >= 0) {\n        // Replace existing mutation\n        this.mutations[existingIndex] = newMutation\n      } else {\n        // Insert new mutation\n        this.mutations.push(newMutation)\n      }\n    }\n  }\n\n  rollback(config?: { isSecondaryRollback?: boolean }): Transaction<T> {\n    const isSecondaryRollback = config?.isSecondaryRollback ?? false\n    if (this.state === `completed`) {\n      throw `You can no longer call .rollback() as the transaction is already completed`\n    }\n\n    this.setState(`failed`)\n\n    // See if there's any other transactions w/ mutations on the same ids\n    // and roll them back as well.\n    if (!isSecondaryRollback) {\n      const mutationIds = new Set()\n      this.mutations.forEach((m) => mutationIds.add(m.globalKey))\n      for (const t of transactions) {\n        t.state === `pending` &&\n          t.mutations.some((m) => mutationIds.has(m.globalKey)) &&\n          t.rollback({ isSecondaryRollback: true })\n      }\n    }\n\n    // Reject the promise\n    this.isPersisted.reject(this.error?.error)\n    this.touchCollection()\n\n    return this\n  }\n\n  // Tell collection that something has changed with the transaction\n  touchCollection(): void {\n    const hasCalled = new Set()\n    for (const mutation of this.mutations) {\n      if (!hasCalled.has(mutation.collection.id)) {\n        mutation.collection.onTransactionStateChange()\n        mutation.collection.commitPendingTransactions()\n        hasCalled.add(mutation.collection.id)\n      }\n    }\n  }\n\n  async commit(): Promise<Transaction<T>> {\n    if (this.state !== `pending`) {\n      throw `You can no longer call .commit() as the transaction is no longer pending`\n    }\n\n    this.setState(`persisting`)\n\n    if (this.mutations.length === 0) {\n      this.setState(`completed`)\n\n      return this\n    }\n\n    // Run mutationFn\n    try {\n      // At this point we know there's at least one mutation\n      // We've already verified mutations is non-empty, so this cast is safe\n      // Use a direct type assertion instead of object spreading to preserve the original type\n      await this.mutationFn({\n        transaction: this as unknown as TransactionWithMutations<T>,\n      })\n\n      this.setState(`completed`)\n      this.touchCollection()\n\n      this.isPersisted.resolve(this)\n    } catch (error) {\n      // Update transaction with error information\n      this.error = {\n        message: error instanceof Error ? error.message : String(error),\n        error: error instanceof Error ? error : new Error(String(error)),\n      }\n\n      // rollback the transaction\n      return this.rollback()\n    }\n\n    return this\n  }\n}\n"],"names":["createDeferred"],"mappings":"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"}

package/dist/cjs/transactions.d.cts

@@ -1,13 +1,13 @@
 import { Deferred } from './deferred.cjs';
-import { PendingMutation, TransactionConfig, TransactionState } from './types.cjs';
+import { MutationFn, PendingMutation, TransactionConfig, TransactionState } from './types.cjs';
 export declare function createTransaction(config: TransactionConfig): Transaction;
 export declare function getActiveTransaction(): Transaction | undefined;
-export declare class Transaction {
+export declare class Transaction<T extends object = Record<string, unknown>> {
     id: string;
     state: TransactionState;
-    mutationFn: import('./types.cjs').MutationFn;
-    mutations: Array<PendingMutation<any>>;
-    isPersisted: Deferred<Transaction>;
+    mutationFn: MutationFn<T>;
+    mutations: Array<PendingMutation<T>>;
+    isPersisted: Deferred<Transaction<T>>;
     autoCommit: boolean;
     createdAt: Date;
     metadata: Record<string, unknown>;
@@ -15,13 +15,13 @@ export declare class Transaction {
         message: string;
         error: Error;
     };
-    constructor(config: TransactionConfig);
+    constructor(config: TransactionConfig<T>);
     setState(newState: TransactionState): void;
-    mutate(callback: () => void): Transaction;
+    mutate(callback: () => void): Transaction<T>;
     applyMutations(mutations: Array<PendingMutation<any>>): void;
     rollback(config?: {
         isSecondaryRollback?: boolean;
-    }): Transaction;
+    }): Transaction<T>;
     touchCollection(): void;
-    commit(): Promise<Transaction>;
+    commit(): Promise<Transaction<T>>;
 }

package/dist/cjs/types.d.cts

@@ -3,42 +3,55 @@ import { Collection } from './collection.cjs';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Transaction } from './transactions.cjs';
 export type TransactionState = `pending` | `persisting` | `completed` | `failed`;
+/**
+ * Represents a utility function that can be attached to a collection
+ */
+export type Fn = (...args: Array<any>) => any;
+/**
+ * A record of utility functions that can be attached to a collection
+ */
+export type UtilsRecord = Record<string, Fn>;
 /**
  * Represents a pending mutation within a transaction
  * Contains information about the original and modified data, as well as metadata
  */
 export interface PendingMutation<T extends object = Record<string, unknown>> {
     mutationId: string;
-    original: Record<string, unknown>;
-    modified: Record<string, unknown>;
-    changes: Record<string, unknown>;
+    original: Partial<T>;
+    modified: T;
+    changes: Partial<T>;
+    globalKey: string;
     key: any;
     type: OperationType;
     metadata: unknown;
     syncMetadata: Record<string, unknown>;
     createdAt: Date;
     updatedAt: Date;
-    collection: Collection<T>;
+    collection: Collection<T, any>;
 }
 /**
  * Configuration options for creating a new transaction
  */
-export type MutationFnParams = {
-    transaction: Transaction;
+export type MutationFnParams<T extends object = Record<string, unknown>> = {
+    transaction: TransactionWithMutations<T>;
 };
-export type MutationFn = (params: MutationFnParams) => Promise<any>;
+export type MutationFn<T extends object = Record<string, unknown>> = (params: MutationFnParams<T>) => Promise<any>;
+/**
+ * Represents a non-empty array (at least one element)
+ */
+export type NonEmptyArray<T> = [T, ...Array<T>];
 /**
  * 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 type TransactionWithMutations<T extends object = Record<string, unknown>> = Transaction<T> & {
+    mutations: NonEmptyArray<PendingMutation<T>>;
 };
-export interface TransactionConfig {
+export interface TransactionConfig<T extends object = Record<string, unknown>> {
     /** Unique identifier for the transaction */
     id?: string;
     autoCommit?: boolean;
-    mutationFn: MutationFn;
+    mutationFn: MutationFn<T>;
     /** Custom metadata to associate with the transaction */
     metadata?: Record<string, unknown>;
 }
@@ -48,9 +61,9 @@ type Value<TExtensions = never> = string | number | boolean | bigint | null | TE
 };
 export type Row<TExtensions = never> = Record<string, Value<TExtensions>>;
 export type OperationType = `insert` | `update` | `delete`;
-export interface SyncConfig<T extends object = Record<string, unknown>> {
+export interface SyncConfig<T extends object = Record<string, unknown>, TKey extends string | number = string | number> {
     sync: (params: {
-        collection: Collection<T>;
+        collection: Collection<T, TKey>;
         begin: () => void;
         write: (message: Omit<ChangeMessage<T>, `key`>) => void;
         commit: () => void;
@@ -61,8 +74,8 @@ export interface SyncConfig<T extends object = Record<string, unknown>> {
      */
     getSyncMetadata?: () => Record<string, unknown>;
 }
-export interface ChangeMessage<T extends object = Record<string, unknown>> {
-    key: any;
+export interface ChangeMessage<T extends object = Record<string, unknown>, TKey extends string | number = string | number> {
+    key: TKey;
     value: T;
     previousValue?: T;
     type: OperationType;
@@ -93,9 +106,9 @@ export interface OperationConfig {
 export interface InsertConfig {
     metadata?: Record<string, unknown>;
 }
-export interface CollectionConfig<T extends object = Record<string, unknown>> {
+export interface CollectionConfig<T extends object = Record<string, unknown>, TKey extends string | number = string | number> {
     id?: string;
-    sync: SyncConfig<T>;
+    sync: SyncConfig<T, TKey>;
     schema?: StandardSchema<T>;
     /**
      * Function to extract the ID from an object
@@ -104,27 +117,27 @@ export interface CollectionConfig<T extends object = Record<string, unknown>> {
      * @returns The ID string for the item
      * @example
      * // For a collection with a 'uuid' field as the primary key
-     * getId: (item) => item.uuid
+     * getKey: (item) => item.uuid
      */
-    getId: (item: T) => any;
+    getKey: (item: T) => TKey;
     /**
      * 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;
+    onInsert?: MutationFn<T>;
     /**
      * 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;
+    onUpdate?: MutationFn<T>;
     /**
      * 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;
+    onDelete?: MutationFn<T>;
 }
 export type ChangesPayload<T extends object = Record<string, unknown>> = Array<ChangeMessage<T>>;
 /**
@@ -151,3 +164,4 @@ export type KeyedNamespacedRow = [unknown, NamespacedRow];
  * a `select` clause.
  */
 export type NamespacedAndKeyedStream = IStreamBuilder<KeyedNamespacedRow>;
+export type ChangeListener<T extends object = Record<string, unknown>, TKey extends string | number = string | number> = (changes: Array<ChangeMessage<T, TKey>>) => void;

package/dist/esm/collection.d.ts

@@ -1,16 +1,28 @@
-import { Derived, Store } from '@tanstack/store';
+import { Store } from '@tanstack/store';
 import { Transaction } from './transactions.js';
 import { SortedMap } from './SortedMap.js';
-import { ChangeMessage, CollectionConfig, InsertConfig, OperationConfig, OptimisticChangeMessage, Transaction as TransactionType } from './types.js';
-export declare const collectionsStore: Store<Map<string, Collection<any>>, (cb: Map<string, Collection<any>>) => Map<string, Collection<any>>>;
+import { ChangeListener, ChangeMessage, CollectionConfig, Fn, InsertConfig, OperationConfig, Transaction as TransactionType, UtilsRecord } from './types.js';
+export declare const collectionsStore: Map<string, CollectionImpl<any, any>>;
+/**
+ * Enhanced Collection interface that includes both data type T and utilities TUtils
+ * @template T - The type of items in the collection
+ * @template TUtils - The utilities record type
+ */
+export interface Collection<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = {}> extends CollectionImpl<T, TKey> {
+    readonly utils: TUtils;
+}
 /**
  * Creates a new Collection instance with the given configuration
  *
  * @template T - The type of items in the collection
- * @param config - Configuration for the collection, including id and sync
- * @returns A new Collection instance
+ * @template TKey - The type of the key for the collection
+ * @template TUtils - The utilities record type
+ * @param options - Collection options with optional utilities
+ * @returns A new Collection with utilities exposed both at top level and under .utils
  */
-export declare function createCollection<T extends object = Record<string, unknown>>(config: CollectionConfig<T>): Collection<T>;
+export declare function createCollection<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = {}>(options: CollectionConfig<T, TKey> & {
+    utils?: TUtils;
+}): Collection<T, TKey, TUtils>;
 /**
  * Preloads a collection with the given configuration
  * Returns a promise that resolves once the sync tool has done its first commit (initial sync is finished)
@@ -37,7 +49,7 @@ export declare function createCollection<T extends object = Record<string, unkno
  * @param config - Configuration for the collection, including id and sync
  * @returns Promise that resolves when the initial sync is finished
  */
-export declare function preloadCollection<T extends object = Record<string, unknown>>(config: CollectionConfig<T>): Promise<Collection<T>>;
+export declare function preloadCollection<T extends object = Record<string, unknown>, TKey extends string | number = string | number>(config: CollectionConfig<T, TKey>): Promise<CollectionImpl<T, TKey>>;
 /**
  * Custom error class for schema validation errors
  */
@@ -52,17 +64,19 @@ export declare class SchemaValidationError extends Error {
         path?: ReadonlyArray<string | number | symbol>;
     }>, message?: string);
 }
-export declare class Collection<T extends object = Record<string, unknown>> {
-    transactions: Store<SortedMap<string, TransactionType>>;
-    optimisticOperations: Derived<Array<OptimisticChangeMessage<T>>>;
-    derivedState: Derived<Map<string, T>>;
-    derivedArray: Derived<Array<T>>;
-    derivedChanges: Derived<Array<ChangeMessage<T>>>;
-    syncedData: Store<Map<string, T>, (cb: Map<string, T>) => Map<string, T>>;
-    syncedMetadata: Store<Map<string, unknown>, (cb: Map<string, unknown>) => Map<string, unknown>>;
+export declare class CollectionImpl<T extends object = Record<string, unknown>, TKey extends string | number = string | number> {
+    transactions: SortedMap<string, Transaction<any>>;
+    syncedData: Map<TKey, T>;
+    syncedMetadata: Map<TKey, unknown>;
+    derivedUpserts: Map<TKey, T>;
+    derivedDeletes: Set<TKey>;
+    private _size;
+    private changeListeners;
+    private changeKeyListeners;
+    utils: Record<string, Fn>;
     private pendingSyncedTransactions;
     private syncedKeys;
-    config: CollectionConfig<T>;
+    config: CollectionConfig<T, TKey>;
     private hasReceivedFirstCommit;
     private onFirstCommitCallbacks;
     /**
@@ -78,15 +92,59 @@ export declare class Collection<T extends object = Record<string, unknown>> {
      * @param config - Configuration object for the collection
      * @throws Error if sync config is missing
      */
-    constructor(config: CollectionConfig<T>);
+    constructor(config: CollectionConfig<T, TKey>);
+    /**
+     * Recompute optimistic state from active transactions
+     */
+    private recomputeOptimisticState;
+    /**
+     * Calculate the current size based on synced data and optimistic changes
+     */
+    private calculateSize;
+    /**
+     * Collect events for optimistic changes
+     */
+    private collectOptimisticChanges;
+    /**
+     * Get the previous value for a key given previous optimistic state
+     */
+    private getPreviousValue;
+    /**
+     * Emit multiple events at once to all listeners
+     */
+    private emitEvents;
+    /**
+     * Get the current value for a key (virtual derived state)
+     */
+    get(key: TKey): T | undefined;
+    /**
+     * Check if a key exists in the collection (virtual derived state)
+     */
+    has(key: TKey): boolean;
+    /**
+     * Get the current size of the collection (cached)
+     */
+    get size(): number;
+    /**
+     * Get all keys (virtual derived state)
+     */
+    keys(): IterableIterator<TKey>;
+    /**
+     * Get all values (virtual derived state)
+     */
+    values(): IterableIterator<T>;
+    /**
+     * Get all entries (virtual derived state)
+     */
+    entries(): IterableIterator<[TKey, T]>;
     /**
      * Attempts to commit pending synced transactions if there are no active transactions
      * This method processes operations from pending transactions and applies them to the synced data
      */
     commitPendingTransactions: () => void;
     private ensureStandardSchema;
-    private getKeyFromId;
-    generateObjectKey(id: any, item: any): string;
+    getKeyFromItem(item: T): TKey;
+    generateGlobalKey(key: any, item: any): string;
     private validateData;
     /**
      * Inserts one or more items into the collection
@@ -107,7 +165,7 @@ export declare class Collection<T extends object = Record<string, unknown>> {
      * // Insert with custom key
      * insert({ text: "Buy groceries" }, { key: "grocery-task" })
      */
-    insert: (data: T | Array<T>, config?: InsertConfig) => Transaction;
+    insert: (data: T | Array<T>, config?: InsertConfig) => Transaction<Record<string, unknown>>;
     /**
      * Updates one or more items in the collection using a callback function
      * @param items - Single item/key or array of items/keys to update
@@ -146,8 +204,10 @@ export declare class Collection<T extends object = Record<string, unknown>> {
      * // Update with metadata
      * update("todo-1", { metadata: { reason: "user update" } }, (draft) => { draft.text = "Updated text" })
      */
-    update<TItem extends object = T>(id: unknown, configOrCallback: ((draft: TItem) => void) | OperationConfig, maybeCallback?: (draft: TItem) => void): TransactionType;
-    update<TItem extends object = T>(ids: Array<unknown>, configOrCallback: ((draft: Array<TItem>) => void) | OperationConfig, maybeCallback?: (draft: Array<TItem>) => void): TransactionType;
+    update<TItem extends object = T>(key: Array<TKey | unknown>, callback: (drafts: Array<TItem>) => void): TransactionType;
+    update<TItem extends object = T>(keys: Array<TKey | unknown>, config: OperationConfig, callback: (drafts: Array<TItem>) => void): TransactionType;
+    update<TItem extends object = T>(id: TKey | unknown, callback: (draft: TItem) => void): TransactionType;
+    update<TItem extends object = T>(id: TKey | unknown, config: OperationConfig, callback: (draft: TItem) => void): TransactionType;
     /**
      * Deletes one or more items from the collection
      * @param ids - Single ID or array of IDs to delete
@@ -163,20 +223,20 @@ export declare class Collection<T extends object = Record<string, unknown>> {
      * // Delete with metadata
      * delete("todo-1", { metadata: { reason: "completed" } })
      */
-    delete: (ids: Array<string> | string, config?: OperationConfig) => TransactionType;
+    delete: (keys: Array<TKey> | TKey, config?: OperationConfig) => TransactionType<any>;
     /**
      * Gets the current state of the collection as a Map
      *
      * @returns A Map containing all items in the collection, with keys as identifiers
      */
-    get state(): Map<string, T>;
+    get state(): Map<TKey, T>;
     /**
      * Gets the current state of the collection as a Map, but only resolves when data is available
      * Waits for the first sync commit to complete before resolving
      *
      * @returns Promise that resolves to a Map containing all items in the collection
      */
-    stateWhenReady(): Promise<Map<string, T>>;
+    stateWhenReady(): Promise<Map<TKey, T>>;
     /**
      * Gets the current state of the collection as an Array
      *
@@ -200,5 +260,34 @@ export declare class Collection<T extends object = Record<string, unknown>> {
      * @param callback - A function that will be called with the changes in the collection
      * @returns A function that can be called to unsubscribe from the changes
      */
-    subscribeChanges(callback: (changes: Array<ChangeMessage<T>>) => void): () => void;
+    subscribeChanges(callback: (changes: Array<ChangeMessage<T>>) => void, { includeInitialState }?: {
+        includeInitialState?: boolean;
+    }): () => void;
+    /**
+     * Subscribe to changes for a specific key
+     */
+    subscribeChangesKey(key: TKey, listener: ChangeListener<T, TKey>, { includeInitialState }?: {
+        includeInitialState?: boolean;
+    }): () => void;
+    /**
+     * Trigger a recomputation when transactions change
+     * This method should be called by the Transaction class when state changes
+     */
+    onTransactionStateChange(): void;
+    private _storeMap;
+    /**
+     * Returns a Tanstack Store Map that is updated when the collection changes
+     * This is a temporary solution to enable the existing framework hooks to work
+     * with the new internals of Collection until they are rewritten.
+     * TODO: Remove this once the framework hooks are rewritten.
+     */
+    asStoreMap(): Store<Map<TKey, T>>;
+    private _storeArray;
+    /**
+     * Returns a Tanstack Store Array that is updated when the collection changes
+     * This is a temporary solution to enable the existing framework hooks to work
+     * with the new internals of Collection until they are rewritten.
+     * TODO: Remove this once the framework hooks are rewritten.
+     */
+    asStoreArray(): Store<Array<T>>;
 }