@durable-streams/state 0.2.5 → 0.2.7

package/README.md

@@ -71,6 +71,7 @@ const db = createStreamDB({
     url: "https://api.example.com/streams/my-stream",
     contentType: "application/json",
   },
+  live: "sse", // optional: true, "long-poll", "sse", or false
   state: schema,
 })
 

package/dist/index.cjs

@@ -120,6 +120,16 @@ var MaterializedState = class {
 //#endregion
 //#region src/stream-db.ts
 /**
+* Build a TanStack collection id for a StreamDB collection.
+*
+* Collection ids must be unique per source stream, not just per schema key,
+* otherwise joining the same collection name from two different streams can
+* collapse to one logical source inside TanStack DB.
+*/
+function getStreamDBCollectionId(streamUrl, collectionName) {
+	return `stream-db:${streamUrl}:${collectionName}`;
+}
+/**
 * Internal event dispatcher that routes stream events to collection handlers
 */
 var EventDispatcher = class {
@@ -140,6 +150,13 @@ var EventDispatcher = class {
 	txidResolvers = new Map();
 	/** Track existing keys per collection for upsert logic */
 	existingKeys = new Map();
+	/** Global sequence counter for insertion ordering */
+	seq = 0;
+	comparableRow(row) {
+		const clone = { ...row };
+		delete clone._seq;
+		return clone;
+	}
 	/**
 	* Register a handler for a specific event type
 	*/
@@ -151,8 +168,9 @@ var EventDispatcher = class {
 	* Dispatch a change event to the appropriate collection.
 	* Writes are buffered until commit() is called via markUpToDate().
 	*/
-	dispatchChange(event) {
+	dispatchChange(event, cursor) {
 		if (!isChangeEvent(event)) return;
+		const eventCursor = event.headers.offset ?? cursor;
 		if (event.headers.txid && typeof event.headers.txid === `string`) this.pendingTxids.add(event.headers.txid);
 		const handler = this.handlers.get(event.type);
 		if (!handler) return;
@@ -163,6 +181,7 @@ var EventDispatcher = class {
 		const originalValue = event.value ?? {};
 		const value = { ...originalValue };
 		value[handler.primaryKey] = event.key;
+		value._seq = this.seq++;
 		if (!this.pendingHandlers.has(handler)) {
 			handler.begin();
 			this.pendingHandlers.add(handler);
@@ -173,10 +192,15 @@ var EventDispatcher = class {
 			operation = existing ? `update` : `insert`;
 		}
 		const keys = this.existingKeys.get(event.type);
+		if (operation === `insert` && keys?.has(event.key)) operation = `update`;
+		else if (operation === `insert` && typeof event.key === `string`) {
+			const existingValue = handler.read(event.key);
+			if (existingValue && (0, __tanstack_db.deepEquals)(this.comparableRow(existingValue), this.comparableRow(value))) operation = `update`;
+		}
 		if (operation === `insert` || operation === `update`) keys?.add(event.key);
 		else keys?.delete(event.key);
 		try {
-			handler.write(value, operation);
+			handler.write(value, operation, eventCursor);
 		} catch (error) {
 			console.error(`[StreamDB] Error in handler.write():`, error);
 			console.error(`[StreamDB] Event that caused error:`, {
@@ -294,16 +318,17 @@ var EventDispatcher = class {
 /**
 * Create a sync config for a stream-backed collection
 */
-function createStreamSyncConfig(eventType, dispatcher, primaryKey) {
+function createStreamSyncConfig(eventType, dispatcher, primaryKey, read) {
 	return { sync: ({ begin, write, commit, markReady, truncate }) => {
 		dispatcher.registerHandler(eventType, {
 			begin,
-			write: (value, type) => {
+			write: (value, type, _cursor) => {
 				write({
 					value,
 					type
 				});
 			},
+			read: (key) => read(key),
 			commit,
 			markReady,
 			truncate,
@@ -448,16 +473,20 @@ function createStateSchema(collections) {
 * ```
 */
 function createStreamDB(options) {
-	const { streamOptions, state, actions: actionsFactory } = options;
-	const stream = new __durable_streams_client.DurableStream(streamOptions);
+	const { streamOptions, state, actions: actionsFactory, live = true, onEvent, onBeforeBatch, onBatch } = options;
+	const stream = options.stream ?? (() => {
+		if (!streamOptions) throw new Error(`createStreamDB requires stream or streamOptions`);
+		return new __durable_streams_client.DurableStream(streamOptions);
+	})();
 	const dispatcher = new EventDispatcher();
+	const streamIdentity = stream.url;
 	const collectionInstances = {};
 	for (const [name, definition] of Object.entries(state)) {
-		const collection = (0, __tanstack_db.createCollection)({
-			id: `stream-db:${name}`,
+		let collection = (0, __tanstack_db.createCollection)({
+			id: getStreamDBCollectionId(streamIdentity, name),
 			schema: definition.schema,
 			getKey: (item) => String(item[definition.primaryKey]),
-			sync: createStreamSyncConfig(definition.type, dispatcher, definition.primaryKey),
+			sync: createStreamSyncConfig(definition.type, dispatcher, definition.primaryKey, (key) => collection.get(key)),
 			startSync: true,
 			gcTime: 0
 		});
@@ -466,6 +495,12 @@ function createStreamDB(options) {
 	let streamResponse = null;
 	const abortController = new AbortController();
 	let consumerStarted = false;
+	let lastConsumedOffset = `-1`;
+	const isAbortLikeError = (err) => {
+		if (abortController.signal.aborted) return true;
+		if (!(err instanceof Error)) return false;
+		return err.name === `AbortError` || err.name === `FetchBackoffAbortError` || err.message === `Stream request was aborted`;
+	};
 	/**
 	* Start the stream consumer (called lazily on first preload)
 	*/
@@ -473,17 +508,30 @@ function createStreamDB(options) {
 		if (consumerStarted) return;
 		consumerStarted = true;
 		streamResponse = await stream.stream({
-			live: true,
+			live,
+			json: true,
 			signal: abortController.signal
 		});
+		streamResponse.closed.catch((err) => {
+			if (isAbortLikeError(err)) return void 0;
+			const error = err instanceof Error ? err : new Error(String(err));
+			console.error(`[StreamDB] Stream consumer closed unexpectedly:`, error);
+			dispatcher.rejectAll(error);
+			return void 0;
+		});
+		lastConsumedOffset = streamResponse.offset;
 		streamResponse.subscribeJson((batch) => {
 			try {
-				for (const event of batch.items) if (isChangeEvent(event)) dispatcher.dispatchChange(event);
-				else if (isControlEvent(event)) dispatcher.dispatchControl(event);
-				if (batch.upToDate) dispatcher.markUpToDate();
+				lastConsumedOffset = batch.offset;
+				onBeforeBatch?.(batch);
+				for (const event of batch.items) if (isChangeEvent(event)) {
+					dispatcher.dispatchChange(event, batch.offset);
+					onEvent?.(event);
+				} else if (isControlEvent(event)) dispatcher.dispatchControl(event);
+				onBatch?.(batch);
+				if (batch.upToDate || dispatcher.ready) dispatcher.markUpToDate();
 			} catch (error) {
 				console.error(`[StreamDB] Error processing batch:`, error);
-				console.error(`[StreamDB] Failed batch:`, batch);
 				dispatcher.rejectAll(error);
 				abortController.abort();
 			}
@@ -492,6 +540,9 @@ function createStreamDB(options) {
 	};
 	const dbMethods = {
 		stream,
+		get offset() {
+			return lastConsumedOffset;
+		},
 		preload: async () => {
 			await startConsumer();
 			await dispatcher.waitForUpToDate();
@@ -502,10 +553,14 @@ function createStreamDB(options) {
 		},
 		utils: { awaitTxId: (txid, timeout) => dispatcher.awaitTxId(txid, timeout) }
 	};
-	const db = {
-		collections: collectionInstances,
-		...dbMethods
-	};
+	const db = Object.create(null);
+	Object.defineProperty(db, `collections`, {
+		value: collectionInstances,
+		enumerable: true,
+		configurable: false,
+		writable: false
+	});
+	Object.defineProperties(db, Object.getOwnPropertyDescriptors(dbMethods));
 	if (actionsFactory) {
 		const actionDefs = actionsFactory({
 			db,
@@ -516,10 +571,13 @@ function createStreamDB(options) {
 			onMutate: def.onMutate,
 			mutationFn: def.mutationFn
 		});
-		return {
-			...db,
-			actions: wrappedActions
-		};
+		Object.defineProperty(db, `actions`, {
+			value: wrappedActions,
+			enumerable: true,
+			configurable: false,
+			writable: false
+		});
+		return db;
 	}
 	return db;
 }
@@ -538,6 +596,18 @@ Object.defineProperty(exports, 'avg', {
     return __tanstack_db.avg;
   }
 });
+Object.defineProperty(exports, 'coalesce', {
+  enumerable: true,
+  get: function () {
+    return __tanstack_db.coalesce;
+  }
+});
+Object.defineProperty(exports, 'concat', {
+  enumerable: true,
+  get: function () {
+    return __tanstack_db.concat;
+  }
+});
 Object.defineProperty(exports, 'count', {
   enumerable: true,
   get: function () {
@@ -550,6 +620,12 @@ Object.defineProperty(exports, 'createCollection', {
     return __tanstack_db.createCollection;
   }
 });
+Object.defineProperty(exports, 'createLiveQueryCollection', {
+  enumerable: true,
+  get: function () {
+    return __tanstack_db.createLiveQueryCollection;
+  }
+});
 Object.defineProperty(exports, 'createOptimisticAction', {
   enumerable: true,
   get: function () {
@@ -558,12 +634,25 @@ Object.defineProperty(exports, 'createOptimisticAction', {
 });
 exports.createStateSchema = createStateSchema
 exports.createStreamDB = createStreamDB
+Object.defineProperty(exports, 'createTransaction', {
+  enumerable: true,
+  get: function () {
+    return __tanstack_db.createTransaction;
+  }
+});
+Object.defineProperty(exports, 'deepEquals', {
+  enumerable: true,
+  get: function () {
+    return __tanstack_db.deepEquals;
+  }
+});
 Object.defineProperty(exports, 'eq', {
   enumerable: true,
   get: function () {
     return __tanstack_db.eq;
   }
 });
+exports.getStreamDBCollectionId = getStreamDBCollectionId
 Object.defineProperty(exports, 'gt', {
   enumerable: true,
   get: function () {
@@ -608,6 +697,12 @@ Object.defineProperty(exports, 'like', {
     return __tanstack_db.like;
   }
 });
+Object.defineProperty(exports, 'localOnlyCollectionOptions', {
+  enumerable: true,
+  get: function () {
+    return __tanstack_db.localOnlyCollectionOptions;
+  }
+});
 Object.defineProperty(exports, 'lt', {
   enumerable: true,
   get: function () {
@@ -644,9 +739,21 @@ Object.defineProperty(exports, 'or', {
     return __tanstack_db.or;
   }
 });
+Object.defineProperty(exports, 'queryOnce', {
+  enumerable: true,
+  get: function () {
+    return __tanstack_db.queryOnce;
+  }
+});
 Object.defineProperty(exports, 'sum', {
   enumerable: true,
   get: function () {
     return __tanstack_db.sum;
   }
+});
+Object.defineProperty(exports, 'toArray', {
+  enumerable: true,
+  get: function () {
+    return __tanstack_db.toArray;
+  }
 });

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-import { Collection, Collection as Collection$1, SyncConfig, and, avg, count, createCollection, createOptimisticAction, createOptimisticAction as createOptimisticAction$1, eq, gt, gte, ilike, inArray, isNull, isUndefined, like, lt, lte, max, min, not, or, sum } from "@tanstack/db";
+import { Collection, Collection as Collection$1, SyncConfig, and, avg, coalesce, concat, count, createCollection, createLiveQueryCollection, createOptimisticAction, createOptimisticAction as createOptimisticAction$1, createTransaction, deepEquals, eq, gt, gte, ilike, inArray, isNull, isUndefined, like, localOnlyCollectionOptions, lt, lte, max, min, not, or, queryOnce, sum, toArray } from "@tanstack/db";
 import { StandardSchemaV1 } from "@standard-schema/spec";
-import { DurableStream, DurableStreamOptions } from "@durable-streams/client";
+import { DurableStream, DurableStreamOptions, JsonBatch, LiveMode } from "@durable-streams/client";
 
 //#region src/types.d.ts
 /**
@@ -27,6 +27,8 @@ type ChangeHeaders = {
   operation: Operation;
   txid?: string;
   timestamp?: string;
+  from?: string;
+  offset?: string;
 };
 /**
 * A change event represents a state change event (insert/update/delete)
@@ -186,12 +188,29 @@ type ActionMap<TActions extends Record<string, ActionDefinition<any>>> = { [K in
 * Options for creating a stream DB
 */
 interface CreateStreamDBOptions<TDef extends StreamStateDefinition = StreamStateDefinition, TActions extends Record<string, ActionDefinition<any>> = Record<string, never>> {
-  /** Options for creating the durable stream (stream is created lazily on preload) */
-  streamOptions: DurableStreamOptions;
+  /** Options for creating a new durable stream. Ignored when `stream` is provided. */
+  streamOptions?: DurableStreamOptions;
+  /** Pre-existing DurableStream instance to reuse (avoids creating a second connection). */
+  stream?: DurableStream;
+  /** Live read mode used by the StreamDB consumer. Defaults to true. */
+  live?: LiveMode;
   /** The stream state definition */
   state: TDef;
   /** Optional factory function to create actions with db and stream context */
   actions?: ActionFactory<TDef, TActions>;
+  /** Called for every ChangeEvent as it flows through the stream consumer. */
+  onEvent?: (event: ChangeEvent) => void;
+  /**
+  * Called once per consumed stream batch before items are dispatched.
+  * Useful when external consumers need batch metadata available during
+  * downstream collection/effect processing.
+  */
+  onBeforeBatch?: (batch: JsonBatch<StateEvent>) => void;
+  /**
+  * Called once per consumed stream batch after items have been dispatched.
+  * Useful for tracking safe offsets for external ack/lease protocols.
+  */
+  onBatch?: (batch: JsonBatch<StateEvent>) => void;
 }
 /**
 * Extract the value type from a CollectionDefinition
@@ -234,6 +253,10 @@ interface StreamDBMethods {
   */
   stream: DurableStream;
   /**
+  * Current stream offset (tracks the last consumed position).
+  */
+  readonly offset: string;
+  /**
   * Preload all collections by consuming the stream until up-to-date
   */
   preload: () => Promise<void>;
@@ -247,6 +270,14 @@ interface StreamDBMethods {
   utils: StreamDBUtils;
 }
 /**
+* Build a TanStack collection id for a StreamDB collection.
+*
+* Collection ids must be unique per source stream, not just per schema key,
+* otherwise joining the same collection name from two different streams can
+* collapse to one logical source inside TanStack DB.
+*/
+declare function getStreamDBCollectionId(streamUrl: string, collectionName: string): string;
+/**
 * Create a state schema definition with typed collections and event helpers
 */
 declare function createStateSchema<T extends Record<string, CollectionDefinition>>(collections: T): StateSchema<T>;
@@ -281,4 +312,4 @@ declare function createStateSchema<T extends Record<string, CollectionDefinition
 declare function createStreamDB<TDef extends StreamStateDefinition, TActions extends Record<string, ActionDefinition<any>> = Record<string, never>>(options: CreateStreamDBOptions<TDef, TActions>): TActions extends Record<string, never> ? StreamDB<TDef> : StreamDBWithActions<TDef, TActions>;
 
 //#endregion
-export { ActionDefinition, ActionFactory, ActionMap, ChangeEvent, ChangeHeaders, Collection, CollectionDefinition, CollectionEventHelpers, CollectionWithHelpers, ControlEvent, CreateStreamDBOptions, MaterializedState, Operation, Row, StateEvent, StateSchema, StreamDB, StreamDBMethods, StreamDBUtils, StreamDBWithActions, StreamStateDefinition, SyncConfig, Value, and, avg, count, createCollection, createOptimisticAction, createStateSchema, createStreamDB, eq, gt, gte, ilike, inArray, isChangeEvent, isControlEvent, isNull, isUndefined, like, lt, lte, max, min, not, or, sum };
+export { ActionDefinition, ActionFactory, ActionMap, ChangeEvent, ChangeHeaders, Collection, CollectionDefinition, CollectionEventHelpers, CollectionWithHelpers, ControlEvent, CreateStreamDBOptions, MaterializedState, Operation, Row, StateEvent, StateSchema, StreamDB, StreamDBMethods, StreamDBUtils, StreamDBWithActions, StreamStateDefinition, SyncConfig, Value, and, avg, coalesce, concat, count, createCollection, createLiveQueryCollection, createOptimisticAction, createStateSchema, createStreamDB, createTransaction, deepEquals, eq, getStreamDBCollectionId, gt, gte, ilike, inArray, isChangeEvent, isControlEvent, isNull, isUndefined, like, localOnlyCollectionOptions, lt, lte, max, min, not, or, queryOnce, sum, toArray };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { Collection, Collection as Collection$1, SyncConfig, and, avg, count, createCollection, createOptimisticAction, createOptimisticAction as createOptimisticAction$1, eq, gt, gte, ilike, inArray, isNull, isUndefined, like, lt, lte, max, min, not, or, sum } from "@tanstack/db";
-import { DurableStream, DurableStreamOptions } from "@durable-streams/client";
+import { Collection, Collection as Collection$1, SyncConfig, and, avg, coalesce, concat, count, createCollection, createLiveQueryCollection, createOptimisticAction, createOptimisticAction as createOptimisticAction$1, createTransaction, deepEquals, eq, gt, gte, ilike, inArray, isNull, isUndefined, like, localOnlyCollectionOptions, lt, lte, max, min, not, or, queryOnce, sum, toArray } from "@tanstack/db";
+import { DurableStream, DurableStreamOptions, JsonBatch, LiveMode } from "@durable-streams/client";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
 //#region src/types.d.ts
@@ -27,6 +27,8 @@ type ChangeHeaders = {
   operation: Operation;
   txid?: string;
   timestamp?: string;
+  from?: string;
+  offset?: string;
 };
 /**
 * A change event represents a state change event (insert/update/delete)
@@ -186,12 +188,29 @@ type ActionMap<TActions extends Record<string, ActionDefinition<any>>> = { [K in
 * Options for creating a stream DB
 */
 interface CreateStreamDBOptions<TDef extends StreamStateDefinition = StreamStateDefinition, TActions extends Record<string, ActionDefinition<any>> = Record<string, never>> {
-  /** Options for creating the durable stream (stream is created lazily on preload) */
-  streamOptions: DurableStreamOptions;
+  /** Options for creating a new durable stream. Ignored when `stream` is provided. */
+  streamOptions?: DurableStreamOptions;
+  /** Pre-existing DurableStream instance to reuse (avoids creating a second connection). */
+  stream?: DurableStream;
+  /** Live read mode used by the StreamDB consumer. Defaults to true. */
+  live?: LiveMode;
   /** The stream state definition */
   state: TDef;
   /** Optional factory function to create actions with db and stream context */
   actions?: ActionFactory<TDef, TActions>;
+  /** Called for every ChangeEvent as it flows through the stream consumer. */
+  onEvent?: (event: ChangeEvent) => void;
+  /**
+  * Called once per consumed stream batch before items are dispatched.
+  * Useful when external consumers need batch metadata available during
+  * downstream collection/effect processing.
+  */
+  onBeforeBatch?: (batch: JsonBatch<StateEvent>) => void;
+  /**
+  * Called once per consumed stream batch after items have been dispatched.
+  * Useful for tracking safe offsets for external ack/lease protocols.
+  */
+  onBatch?: (batch: JsonBatch<StateEvent>) => void;
 }
 /**
 * Extract the value type from a CollectionDefinition
@@ -234,6 +253,10 @@ interface StreamDBMethods {
   */
   stream: DurableStream;
   /**
+  * Current stream offset (tracks the last consumed position).
+  */
+  readonly offset: string;
+  /**
   * Preload all collections by consuming the stream until up-to-date
   */
   preload: () => Promise<void>;
@@ -247,6 +270,14 @@ interface StreamDBMethods {
   utils: StreamDBUtils;
 }
 /**
+* Build a TanStack collection id for a StreamDB collection.
+*
+* Collection ids must be unique per source stream, not just per schema key,
+* otherwise joining the same collection name from two different streams can
+* collapse to one logical source inside TanStack DB.
+*/
+declare function getStreamDBCollectionId(streamUrl: string, collectionName: string): string;
+/**
 * Create a state schema definition with typed collections and event helpers
 */
 declare function createStateSchema<T extends Record<string, CollectionDefinition>>(collections: T): StateSchema<T>;
@@ -281,4 +312,4 @@ declare function createStateSchema<T extends Record<string, CollectionDefinition
 declare function createStreamDB<TDef extends StreamStateDefinition, TActions extends Record<string, ActionDefinition<any>> = Record<string, never>>(options: CreateStreamDBOptions<TDef, TActions>): TActions extends Record<string, never> ? StreamDB<TDef> : StreamDBWithActions<TDef, TActions>;
 
 //#endregion
-export { ActionDefinition, ActionFactory, ActionMap, ChangeEvent, ChangeHeaders, Collection, CollectionDefinition, CollectionEventHelpers, CollectionWithHelpers, ControlEvent, CreateStreamDBOptions, MaterializedState, Operation, Row, StateEvent, StateSchema, StreamDB, StreamDBMethods, StreamDBUtils, StreamDBWithActions, StreamStateDefinition, SyncConfig, Value, and, avg, count, createCollection, createOptimisticAction, createStateSchema, createStreamDB, eq, gt, gte, ilike, inArray, isChangeEvent, isControlEvent, isNull, isUndefined, like, lt, lte, max, min, not, or, sum };
+export { ActionDefinition, ActionFactory, ActionMap, ChangeEvent, ChangeHeaders, Collection, CollectionDefinition, CollectionEventHelpers, CollectionWithHelpers, ControlEvent, CreateStreamDBOptions, MaterializedState, Operation, Row, StateEvent, StateSchema, StreamDB, StreamDBMethods, StreamDBUtils, StreamDBWithActions, StreamStateDefinition, SyncConfig, Value, and, avg, coalesce, concat, count, createCollection, createLiveQueryCollection, createOptimisticAction, createStateSchema, createStreamDB, createTransaction, deepEquals, eq, getStreamDBCollectionId, gt, gte, ilike, inArray, isChangeEvent, isControlEvent, isNull, isUndefined, like, localOnlyCollectionOptions, lt, lte, max, min, not, or, queryOnce, sum, toArray };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { and, avg, count, createCollection, createCollection as createCollection$1, createOptimisticAction, createOptimisticAction as createOptimisticAction$1, eq, gt, gte, ilike, inArray, isNull, isUndefined, like, lt, lte, max, min, not, or, sum } from "@tanstack/db";
+import { and, avg, coalesce, concat, count, createCollection, createCollection as createCollection$1, createLiveQueryCollection, createOptimisticAction, createOptimisticAction as createOptimisticAction$1, createTransaction, deepEquals, deepEquals as deepEquals$1, eq, gt, gte, ilike, inArray, isNull, isUndefined, like, localOnlyCollectionOptions, lt, lte, max, min, not, or, queryOnce, sum, toArray } from "@tanstack/db";
 import { DurableStream } from "@durable-streams/client";
 
 //#region src/types.ts
@@ -96,6 +96,16 @@ var MaterializedState = class {
 //#endregion
 //#region src/stream-db.ts
 /**
+* Build a TanStack collection id for a StreamDB collection.
+*
+* Collection ids must be unique per source stream, not just per schema key,
+* otherwise joining the same collection name from two different streams can
+* collapse to one logical source inside TanStack DB.
+*/
+function getStreamDBCollectionId(streamUrl, collectionName) {
+	return `stream-db:${streamUrl}:${collectionName}`;
+}
+/**
 * Internal event dispatcher that routes stream events to collection handlers
 */
 var EventDispatcher = class {
@@ -116,6 +126,13 @@ var EventDispatcher = class {
 	txidResolvers = new Map();
 	/** Track existing keys per collection for upsert logic */
 	existingKeys = new Map();
+	/** Global sequence counter for insertion ordering */
+	seq = 0;
+	comparableRow(row) {
+		const clone = { ...row };
+		delete clone._seq;
+		return clone;
+	}
 	/**
 	* Register a handler for a specific event type
 	*/
@@ -127,8 +144,9 @@ var EventDispatcher = class {
 	* Dispatch a change event to the appropriate collection.
 	* Writes are buffered until commit() is called via markUpToDate().
 	*/
-	dispatchChange(event) {
+	dispatchChange(event, cursor) {
 		if (!isChangeEvent(event)) return;
+		const eventCursor = event.headers.offset ?? cursor;
 		if (event.headers.txid && typeof event.headers.txid === `string`) this.pendingTxids.add(event.headers.txid);
 		const handler = this.handlers.get(event.type);
 		if (!handler) return;
@@ -139,6 +157,7 @@ var EventDispatcher = class {
 		const originalValue = event.value ?? {};
 		const value = { ...originalValue };
 		value[handler.primaryKey] = event.key;
+		value._seq = this.seq++;
 		if (!this.pendingHandlers.has(handler)) {
 			handler.begin();
 			this.pendingHandlers.add(handler);
@@ -149,10 +168,15 @@ var EventDispatcher = class {
 			operation = existing ? `update` : `insert`;
 		}
 		const keys = this.existingKeys.get(event.type);
+		if (operation === `insert` && keys?.has(event.key)) operation = `update`;
+		else if (operation === `insert` && typeof event.key === `string`) {
+			const existingValue = handler.read(event.key);
+			if (existingValue && deepEquals$1(this.comparableRow(existingValue), this.comparableRow(value))) operation = `update`;
+		}
 		if (operation === `insert` || operation === `update`) keys?.add(event.key);
 		else keys?.delete(event.key);
 		try {
-			handler.write(value, operation);
+			handler.write(value, operation, eventCursor);
 		} catch (error) {
 			console.error(`[StreamDB] Error in handler.write():`, error);
 			console.error(`[StreamDB] Event that caused error:`, {
@@ -270,16 +294,17 @@ var EventDispatcher = class {
 /**
 * Create a sync config for a stream-backed collection
 */
-function createStreamSyncConfig(eventType, dispatcher, primaryKey) {
+function createStreamSyncConfig(eventType, dispatcher, primaryKey, read) {
 	return { sync: ({ begin, write, commit, markReady, truncate }) => {
 		dispatcher.registerHandler(eventType, {
 			begin,
-			write: (value, type) => {
+			write: (value, type, _cursor) => {
 				write({
 					value,
 					type
 				});
 			},
+			read: (key) => read(key),
 			commit,
 			markReady,
 			truncate,
@@ -424,16 +449,20 @@ function createStateSchema(collections) {
 * ```
 */
 function createStreamDB(options) {
-	const { streamOptions, state, actions: actionsFactory } = options;
-	const stream = new DurableStream(streamOptions);
+	const { streamOptions, state, actions: actionsFactory, live = true, onEvent, onBeforeBatch, onBatch } = options;
+	const stream = options.stream ?? (() => {
+		if (!streamOptions) throw new Error(`createStreamDB requires stream or streamOptions`);
+		return new DurableStream(streamOptions);
+	})();
 	const dispatcher = new EventDispatcher();
+	const streamIdentity = stream.url;
 	const collectionInstances = {};
 	for (const [name, definition] of Object.entries(state)) {
-		const collection = createCollection$1({
-			id: `stream-db:${name}`,
+		let collection = createCollection$1({
+			id: getStreamDBCollectionId(streamIdentity, name),
 			schema: definition.schema,
 			getKey: (item) => String(item[definition.primaryKey]),
-			sync: createStreamSyncConfig(definition.type, dispatcher, definition.primaryKey),
+			sync: createStreamSyncConfig(definition.type, dispatcher, definition.primaryKey, (key) => collection.get(key)),
 			startSync: true,
 			gcTime: 0
 		});
@@ -442,6 +471,12 @@ function createStreamDB(options) {
 	let streamResponse = null;
 	const abortController = new AbortController();
 	let consumerStarted = false;
+	let lastConsumedOffset = `-1`;
+	const isAbortLikeError = (err) => {
+		if (abortController.signal.aborted) return true;
+		if (!(err instanceof Error)) return false;
+		return err.name === `AbortError` || err.name === `FetchBackoffAbortError` || err.message === `Stream request was aborted`;
+	};
 	/**
 	* Start the stream consumer (called lazily on first preload)
 	*/
@@ -449,17 +484,30 @@ function createStreamDB(options) {
 		if (consumerStarted) return;
 		consumerStarted = true;
 		streamResponse = await stream.stream({
-			live: true,
+			live,
+			json: true,
 			signal: abortController.signal
 		});
+		streamResponse.closed.catch((err) => {
+			if (isAbortLikeError(err)) return void 0;
+			const error = err instanceof Error ? err : new Error(String(err));
+			console.error(`[StreamDB] Stream consumer closed unexpectedly:`, error);
+			dispatcher.rejectAll(error);
+			return void 0;
+		});
+		lastConsumedOffset = streamResponse.offset;
 		streamResponse.subscribeJson((batch) => {
 			try {
-				for (const event of batch.items) if (isChangeEvent(event)) dispatcher.dispatchChange(event);
-				else if (isControlEvent(event)) dispatcher.dispatchControl(event);
-				if (batch.upToDate) dispatcher.markUpToDate();
+				lastConsumedOffset = batch.offset;
+				onBeforeBatch?.(batch);
+				for (const event of batch.items) if (isChangeEvent(event)) {
+					dispatcher.dispatchChange(event, batch.offset);
+					onEvent?.(event);
+				} else if (isControlEvent(event)) dispatcher.dispatchControl(event);
+				onBatch?.(batch);
+				if (batch.upToDate || dispatcher.ready) dispatcher.markUpToDate();
 			} catch (error) {
 				console.error(`[StreamDB] Error processing batch:`, error);
-				console.error(`[StreamDB] Failed batch:`, batch);
 				dispatcher.rejectAll(error);
 				abortController.abort();
 			}
@@ -468,6 +516,9 @@ function createStreamDB(options) {
 	};
 	const dbMethods = {
 		stream,
+		get offset() {
+			return lastConsumedOffset;
+		},
 		preload: async () => {
 			await startConsumer();
 			await dispatcher.waitForUpToDate();
@@ -478,10 +529,14 @@ function createStreamDB(options) {
 		},
 		utils: { awaitTxId: (txid, timeout) => dispatcher.awaitTxId(txid, timeout) }
 	};
-	const db = {
-		collections: collectionInstances,
-		...dbMethods
-	};
+	const db = Object.create(null);
+	Object.defineProperty(db, `collections`, {
+		value: collectionInstances,
+		enumerable: true,
+		configurable: false,
+		writable: false
+	});
+	Object.defineProperties(db, Object.getOwnPropertyDescriptors(dbMethods));
 	if (actionsFactory) {
 		const actionDefs = actionsFactory({
 			db,
@@ -492,13 +547,16 @@ function createStreamDB(options) {
 			onMutate: def.onMutate,
 			mutationFn: def.mutationFn
 		});
-		return {
-			...db,
-			actions: wrappedActions
-		};
+		Object.defineProperty(db, `actions`, {
+			value: wrappedActions,
+			enumerable: true,
+			configurable: false,
+			writable: false
+		});
+		return db;
 	}
 	return db;
 }
 
 //#endregion
-export { MaterializedState, and, avg, count, createCollection, createOptimisticAction, createStateSchema, createStreamDB, eq, gt, gte, ilike, inArray, isChangeEvent, isControlEvent, isNull, isUndefined, like, lt, lte, max, min, not, or, sum };
+export { MaterializedState, and, avg, coalesce, concat, count, createCollection, createLiveQueryCollection, createOptimisticAction, createStateSchema, createStreamDB, createTransaction, deepEquals, eq, getStreamDBCollectionId, gt, gte, ilike, inArray, isChangeEvent, isControlEvent, isNull, isUndefined, like, localOnlyCollectionOptions, lt, lte, max, min, not, or, queryOnce, sum, toArray };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@durable-streams/state",
   "description": "State change event protocol for Durable Streams",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "author": "Durable Stream contributors",
   "license": "Apache-2.0",
   "repository": {
@@ -50,16 +50,13 @@
   ],
   "dependencies": {
     "@standard-schema/spec": "^1.0.0",
-    "@durable-streams/client": "0.2.3"
-  },
-  "peerDependencies": {
-    "@tanstack/db": ">=0.5.0"
+    "@tanstack/db": "^0.6.0",
+    "@durable-streams/client": "0.2.4"
   },
   "devDependencies": {
-    "@tanstack/db": "latest",
     "@tanstack/intent": "latest",
     "tsdown": "^0.9.0",
-    "@durable-streams/server": "0.3.1"
+    "@durable-streams/server": "0.3.3"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/index.ts

@@ -15,7 +15,11 @@ export { isChangeEvent, isControlEvent } from "./types"
 export { MaterializedState } from "./materialized-state"
 
 // Stream DB
-export { createStreamDB, createStateSchema } from "./stream-db"
+export {
+  createStreamDB,
+  createStateSchema,
+  getStreamDBCollectionId,
+} from "./stream-db"
 export type {
   CollectionDefinition,
   CollectionEventHelpers,
@@ -37,7 +41,12 @@ export type {
 export type { Collection, SyncConfig } from "@tanstack/db"
 export {
   createCollection,
+  createLiveQueryCollection,
   createOptimisticAction,
+  createTransaction,
+  deepEquals,
+  localOnlyCollectionOptions,
+  queryOnce,
   // Comparison operators
   eq,
   gt,
@@ -60,4 +69,8 @@ export {
   avg,
   min,
   max,
+  // Includes/projection functions
+  concat,
+  coalesce,
+  toArray,
 } from "@tanstack/db"

package/src/stream-db.ts

@@ -1,4 +1,8 @@
-import { createCollection, createOptimisticAction } from "@tanstack/db"
+import {
+  createCollection,
+  createOptimisticAction,
+  deepEquals,
+} from "@tanstack/db"
 import { DurableStream as DurableStreamClass } from "@durable-streams/client"
 import { isChangeEvent, isControlEvent } from "./types"
 import type { Collection, SyncConfig } from "@tanstack/db"
@@ -7,6 +11,8 @@ import type { StandardSchemaV1 } from "@standard-schema/spec"
 import type {
   DurableStream,
   DurableStreamOptions,
+  JsonBatch,
+  LiveMode,
   StreamResponse,
 } from "@durable-streams/client"
 
@@ -119,12 +125,29 @@ export interface CreateStreamDBOptions<
     never
   >,
 > {
-  /** Options for creating the durable stream (stream is created lazily on preload) */
-  streamOptions: DurableStreamOptions
+  /** Options for creating a new durable stream. Ignored when `stream` is provided. */
+  streamOptions?: DurableStreamOptions
+  /** Pre-existing DurableStream instance to reuse (avoids creating a second connection). */
+  stream?: DurableStream
+  /** Live read mode used by the StreamDB consumer. Defaults to true. */
+  live?: LiveMode
   /** The stream state definition */
   state: TDef
   /** Optional factory function to create actions with db and stream context */
   actions?: ActionFactory<TDef, TActions>
+  /** Called for every ChangeEvent as it flows through the stream consumer. */
+  onEvent?: (event: ChangeEvent) => void
+  /**
+   * Called once per consumed stream batch before items are dispatched.
+   * Useful when external consumers need batch metadata available during
+   * downstream collection/effect processing.
+   */
+  onBeforeBatch?: (batch: JsonBatch<StateEvent>) => void
+  /**
+   * Called once per consumed stream batch after items have been dispatched.
+   * Useful for tracking safe offsets for external ack/lease protocols.
+   */
+  onBatch?: (batch: JsonBatch<StateEvent>) => void
 }
 
 /**
@@ -179,6 +202,11 @@ export interface StreamDBMethods {
    */
   stream: DurableStream
 
+  /**
+   * Current stream offset (tracks the last consumed position).
+   */
+  readonly offset: string
+
   /**
    * Preload all collections by consuming the stream until up-to-date
    */
@@ -195,6 +223,20 @@ export interface StreamDBMethods {
   utils: StreamDBUtils
 }
 
+/**
+ * Build a TanStack collection id for a StreamDB collection.
+ *
+ * Collection ids must be unique per source stream, not just per schema key,
+ * otherwise joining the same collection name from two different streams can
+ * collapse to one logical source inside TanStack DB.
+ */
+export function getStreamDBCollectionId(
+  streamUrl: string,
+  collectionName: string
+): string {
+  return `stream-db:${streamUrl}:${collectionName}`
+}
+
 // ============================================================================
 // Internal Event Dispatcher
 // ============================================================================
@@ -204,7 +246,12 @@ export interface StreamDBMethods {
  */
 interface CollectionSyncHandler {
   begin: () => void
-  write: (value: object, type: `insert` | `update` | `delete`) => void
+  write: (
+    value: object,
+    type: `insert` | `update` | `delete`,
+    cursor?: string
+  ) => void
+  read: (key: string) => object | undefined
   commit: () => void
   markReady: () => void
   truncate: () => void
@@ -247,6 +294,15 @@ class EventDispatcher {
   /** Track existing keys per collection for upsert logic */
   private existingKeys = new Map<string, Set<string>>()
 
+  /** Global sequence counter for insertion ordering */
+  private seq = 0
+
+  private comparableRow(row: object): Record<string, unknown> {
+    const clone = { ...(row as Record<string, unknown>) }
+    delete clone._seq
+    return clone
+  }
+
   /**
    * Register a handler for a specific event type
    */
@@ -262,9 +318,11 @@ class EventDispatcher {
    * Dispatch a change event to the appropriate collection.
    * Writes are buffered until commit() is called via markUpToDate().
    */
-  dispatchChange(event: StateEvent): void {
+  dispatchChange(event: StateEvent, cursor?: string): void {
     if (!isChangeEvent(event)) return
 
+    const eventCursor = event.headers.offset ?? cursor
+
     // Check for txid in headers and collect it
     if (event.headers.txid && typeof event.headers.txid === `string`) {
       this.pendingTxids.add(event.headers.txid)
@@ -296,6 +354,9 @@ class EventDispatcher {
     // Set the primary key field on the value object from the event key
     ;(value as any)[handler.primaryKey] = event.key
 
+    // Stamp global insertion order for cross-collection sorting
+    ;(value as any)._seq = this.seq++
+
     // Begin transaction on first write to this handler
     if (!this.pendingHandlers.has(handler)) {
       handler.begin()
@@ -309,8 +370,24 @@ class EventDispatcher {
       operation = existing ? `update` : `insert`
     }
 
-    // Track key existence for upsert logic
     const keys = this.existingKeys.get(event.type)
+
+    // Live stream reconnects can replay an already-synced insert for the same
+    // row. Normalize that case to update so observation replays remain
+    // idempotent instead of tripping TanStack DB's duplicate-key path.
+    if (operation === `insert` && keys?.has(event.key)) {
+      operation = `update`
+    } else if (operation === `insert` && typeof event.key === `string`) {
+      const existingValue = handler.read(event.key)
+      if (
+        existingValue &&
+        deepEquals(this.comparableRow(existingValue), this.comparableRow(value))
+      ) {
+        operation = `update`
+      }
+    }
+
+    // Track key existence for upsert logic
     if (operation === `insert` || operation === `update`) {
       keys?.add(event.key)
     } else {
@@ -319,7 +396,7 @@ class EventDispatcher {
     }
 
     try {
-      handler.write(value, operation)
+      handler.write(value, operation, eventCursor)
     } catch (error) {
       console.error(`[StreamDB] Error in handler.write():`, error)
       console.error(`[StreamDB] Event that caused error:`, {
@@ -504,19 +581,21 @@ class EventDispatcher {
 function createStreamSyncConfig<T extends object>(
   eventType: string,
   dispatcher: EventDispatcher,
-  primaryKey: string
+  primaryKey: string,
+  read: (key: string) => T | undefined
 ): SyncConfig<T, string> {
   return {
     sync: ({ begin, write, commit, markReady, truncate }) => {
       // Register this collection's handler with the dispatcher
       dispatcher.registerHandler(eventType, {
         begin,
-        write: (value, type) => {
+        write: (value, type, _cursor) => {
           write({
             value: value as T,
             type,
           })
         },
+        read: (key) => read(key),
         commit,
         markReady,
         truncate,
@@ -762,26 +841,45 @@ export function createStreamDB<
 ): TActions extends Record<string, never>
   ? StreamDB<TDef>
   : StreamDBWithActions<TDef, TActions> {
-  const { streamOptions, state, actions: actionsFactory } = options
-
-  // Create a stream handle (lightweight, doesn't connect until stream() is called)
-  const stream = new DurableStreamClass(streamOptions)
+  const {
+    streamOptions,
+    state,
+    actions: actionsFactory,
+    live = true,
+    onEvent,
+    onBeforeBatch,
+    onBatch,
+  } = options
+
+  // Reuse provided stream or create a new one
+  const stream =
+    options.stream ??
+    (() => {
+      if (!streamOptions) {
+        throw new Error(`createStreamDB requires stream or streamOptions`)
+      }
+      return new DurableStreamClass(streamOptions)
+    })()
 
   // Create the event dispatcher
   const dispatcher = new EventDispatcher()
 
+  const streamIdentity = stream.url
+
   // Create TanStack DB collections for each definition
   const collectionInstances: Record<string, Collection<object, string>> = {}
 
   for (const [name, definition] of Object.entries(state)) {
-    const collection = createCollection({
-      id: `stream-db:${name}`,
+    // eslint-disable-next-line prefer-const -- self-referential: collection.get() used in its own sync config
+    let collection: Collection<object, string> = createCollection({
+      id: getStreamDBCollectionId(streamIdentity, name),
       schema: definition.schema as StandardSchemaV1<object>,
       getKey: (item: any) => String(item[definition.primaryKey]),
       sync: createStreamSyncConfig(
         definition.type,
         dispatcher,
-        definition.primaryKey
+        definition.primaryKey,
+        (key) => collection.get(key) as object | undefined
       ),
       startSync: true, // Start syncing immediately
       // Disable GC - we manage lifecycle via db.close()
@@ -797,6 +895,20 @@ export function createStreamDB<
   let streamResponse: StreamResponse<StateEvent> | null = null
   const abortController = new AbortController()
   let consumerStarted = false
+  let lastConsumedOffset = `-1`
+  const isAbortLikeError = (err: unknown): boolean => {
+    if (abortController.signal.aborted) {
+      return true
+    }
+    if (!(err instanceof Error)) {
+      return false
+    }
+    return (
+      err.name === `AbortError` ||
+      err.name === `FetchBackoffAbortError` ||
+      err.message === `Stream request was aborted`
+    )
+  }
 
   /**
    * Start the stream consumer (called lazily on first preload)
@@ -807,33 +919,49 @@ export function createStreamDB<
 
     // Start streaming (this is where the connection actually happens)
     streamResponse = await stream.stream<StateEvent>({
-      live: true,
+      live,
+      json: true,
       signal: abortController.signal,
     })
+    // StreamDB consumes batches via subscribeJson(); it does not await the
+    // session's closed promise. Swallow that terminal rejection so aborting
+    // the live session during db.close() doesn't surface as an unhandled
+    // rejection after the real error has already been routed elsewhere.
+    void streamResponse.closed.catch((err) => {
+      if (isAbortLikeError(err)) {
+        return undefined
+      }
+      const error = err instanceof Error ? err : new Error(String(err))
+      console.error(`[StreamDB] Stream consumer closed unexpectedly:`, error)
+      dispatcher.rejectAll(error)
+      return undefined
+    })
+    lastConsumedOffset = streamResponse.offset
 
     // Process events as they come in
     streamResponse.subscribeJson((batch) => {
       try {
+        lastConsumedOffset = batch.offset
+        onBeforeBatch?.(batch)
+
         for (const event of batch.items) {
           if (isChangeEvent(event)) {
-            dispatcher.dispatchChange(event)
+            dispatcher.dispatchChange(event, batch.offset)
+            onEvent?.(event)
           } else if (isControlEvent(event)) {
             dispatcher.dispatchControl(event)
           }
         }
 
-        // Check batch-level up-to-date signal
-        if (batch.upToDate) {
+        onBatch?.(batch)
+
+        if (batch.upToDate || dispatcher.ready) {
           dispatcher.markUpToDate()
         }
       } catch (error) {
         console.error(`[StreamDB] Error processing batch:`, error)
-        console.error(`[StreamDB] Failed batch:`, batch)
-        // Reject all waiting preload promises
         dispatcher.rejectAll(error as Error)
-        // Abort the stream to stop further processing
         abortController.abort()
-        // Don't rethrow - we've already rejected the promise
       }
       return Promise.resolve()
     })
@@ -842,6 +970,9 @@ export function createStreamDB<
   // Build the StreamDB object with methods
   const dbMethods: StreamDBMethods = {
     stream,
+    get offset() {
+      return lastConsumedOffset
+    },
     preload: async () => {
       await startConsumer()
       await dispatcher.waitForUpToDate()
@@ -857,11 +988,14 @@ export function createStreamDB<
     },
   }
 
-  // Combine collections with methods
-  const db = {
-    collections: collectionInstances,
-    ...dbMethods,
-  } as unknown as StreamDB<TDef>
+  const db = Object.create(null) as StreamDB<TDef>
+  Object.defineProperty(db, `collections`, {
+    value: collectionInstances,
+    enumerable: true,
+    configurable: false,
+    writable: false,
+  })
+  Object.defineProperties(db, Object.getOwnPropertyDescriptors(dbMethods))
 
   // If actions factory is provided, wrap actions and return db with actions
   if (actionsFactory) {
@@ -877,10 +1011,13 @@ export function createStreamDB<
       })
     }
 
-    return {
-      ...db,
-      actions: wrappedActions,
-    } as any
+    Object.defineProperty(db, `actions`, {
+      value: wrappedActions,
+      enumerable: true,
+      configurable: false,
+      writable: false,
+    })
+    return db as any
   }
 
   return db as any

package/src/types.ts

@@ -31,6 +31,8 @@ export type ChangeHeaders = {
   operation: Operation
   txid?: string
   timestamp?: string
+  from?: string
+  offset?: string
 }
 
 /**