@durable-streams/state 0.2.9 → 0.3.1

package/dist/src-AIE5IYwJ.cjs

@@ -0,0 +1,228 @@
+"use strict";
+
+//#region src/types.ts
+/**
+* Type guard to check if an event is a change event
+*/
+function isChangeEvent(event) {
+	return event != null && `operation` in event.headers;
+}
+/**
+* Type guard to check if an event is a control event
+*/
+function isControlEvent(event) {
+	return event != null && `control` in event.headers;
+}
+
+//#endregion
+//#region src/materialized-state.ts
+/**
+* MaterializedState maintains an in-memory view of state from change events.
+*
+* It organizes data by type, where each type contains a map of key -> value.
+* This supports multi-type streams where different entity types can coexist.
+*/
+var MaterializedState = class {
+	data;
+	constructor() {
+		this.data = new Map();
+	}
+	/**
+	* Apply a single change event to update the materialized state
+	*/
+	apply(event) {
+		const { type, key, value, headers } = event;
+		let typeMap = this.data.get(type);
+		if (!typeMap) {
+			typeMap = new Map();
+			this.data.set(type, typeMap);
+		}
+		switch (headers.operation) {
+			case `insert`:
+				typeMap.set(key, value);
+				break;
+			case `update`:
+				typeMap.set(key, value);
+				break;
+			case `upsert`:
+				typeMap.set(key, value);
+				break;
+			case `delete`:
+				typeMap.delete(key);
+				break;
+		}
+	}
+	/**
+	* Apply a batch of change events
+	*/
+	applyBatch(events) {
+		for (const event of events) this.apply(event);
+	}
+	/**
+	* Get a specific value by type and key
+	*/
+	get(type, key) {
+		const typeMap = this.data.get(type);
+		if (!typeMap) return void 0;
+		return typeMap.get(key);
+	}
+	/**
+	* Get all entries for a specific type
+	*/
+	getType(type) {
+		return this.data.get(type) || new Map();
+	}
+	/**
+	* Clear all state
+	*/
+	clear() {
+		this.data.clear();
+	}
+	/**
+	* Get the number of types in the state
+	*/
+	get typeCount() {
+		return this.data.size;
+	}
+	/**
+	* Get all type names
+	*/
+	get types() {
+		return Array.from(this.data.keys());
+	}
+};
+
+//#endregion
+//#region src/schema.ts
+/**
+* Reserved collection names that would collide with StreamDB properties
+* (collections are now namespaced, but we still prevent internal name collisions)
+*/
+const RESERVED_COLLECTION_NAMES = new Set([
+	`collections`,
+	`preload`,
+	`close`,
+	`utils`,
+	`actions`
+]);
+/**
+* Create helper functions for a collection
+*/
+function createCollectionHelpers(eventType, primaryKey, schema) {
+	return {
+		insert: ({ key, value, headers }) => {
+			const result = schema[`~standard`].validate(value);
+			if (`issues` in result) throw new Error(`Validation failed for ${eventType} insert: ${result.issues?.map((i) => i.message).join(`, `) ?? `Unknown validation error`}`);
+			const derived = value[primaryKey];
+			const finalKey = key ?? (derived != null && derived !== `` ? String(derived) : void 0);
+			if (finalKey == null || finalKey === ``) throw new Error(`Cannot create ${eventType} insert event: must provide either 'key' or a value with a non-empty '${primaryKey}' field`);
+			return {
+				type: eventType,
+				key: finalKey,
+				value,
+				headers: {
+					...headers,
+					operation: `insert`
+				}
+			};
+		},
+		update: ({ key, value, oldValue, headers }) => {
+			const result = schema[`~standard`].validate(value);
+			if (`issues` in result) throw new Error(`Validation failed for ${eventType} update: ${result.issues?.map((i) => i.message).join(`, `) ?? `Unknown validation error`}`);
+			if (oldValue !== void 0) {
+				const oldResult = schema[`~standard`].validate(oldValue);
+				if (`issues` in oldResult) throw new Error(`Validation failed for ${eventType} update (oldValue): ${oldResult.issues?.map((i) => i.message).join(`, `) ?? `Unknown validation error`}`);
+			}
+			const derived = value[primaryKey];
+			const finalKey = key ?? (derived != null && derived !== `` ? String(derived) : void 0);
+			if (finalKey == null || finalKey === ``) throw new Error(`Cannot create ${eventType} update event: must provide either 'key' or a value with a non-empty '${primaryKey}' field`);
+			return {
+				type: eventType,
+				key: finalKey,
+				value,
+				old_value: oldValue,
+				headers: {
+					...headers,
+					operation: `update`
+				}
+			};
+		},
+		delete: ({ key, oldValue, headers }) => {
+			if (oldValue !== void 0) {
+				const result = schema[`~standard`].validate(oldValue);
+				if (`issues` in result) throw new Error(`Validation failed for ${eventType} delete (oldValue): ${result.issues?.map((i) => i.message).join(`, `) ?? `Unknown validation error`}`);
+			}
+			const finalKey = key ?? (oldValue ? String(oldValue[primaryKey]) : void 0);
+			if (!finalKey) throw new Error(`Cannot create ${eventType} delete event: must provide either 'key' or 'oldValue' with a ${primaryKey} field`);
+			return {
+				type: eventType,
+				key: finalKey,
+				old_value: oldValue,
+				headers: {
+					...headers,
+					operation: `delete`
+				}
+			};
+		},
+		upsert: ({ key, value, headers }) => {
+			const result = schema[`~standard`].validate(value);
+			if (`issues` in result) throw new Error(`Validation failed for ${eventType} upsert: ${result.issues?.map((i) => i.message).join(`, `) ?? `Unknown validation error`}`);
+			const derived = value[primaryKey];
+			const finalKey = key ?? (derived != null && derived !== `` ? String(derived) : void 0);
+			if (finalKey == null || finalKey === ``) throw new Error(`Cannot create ${eventType} upsert event: must provide either 'key' or a value with a non-empty '${primaryKey}' field`);
+			return {
+				type: eventType,
+				key: finalKey,
+				value,
+				headers: {
+					...headers,
+					operation: `upsert`
+				}
+			};
+		}
+	};
+}
+/**
+* Create a state schema definition with typed collections and event helpers
+*/
+function createStateSchema(collections) {
+	for (const name of Object.keys(collections)) if (RESERVED_COLLECTION_NAMES.has(name)) throw new Error(`Reserved collection name "${name}" - this would collide with StreamDB properties (${Array.from(RESERVED_COLLECTION_NAMES).join(`, `)})`);
+	const typeToCollection = new Map();
+	for (const [collectionName, def] of Object.entries(collections)) {
+		const existing = typeToCollection.get(def.type);
+		if (existing) throw new Error(`Duplicate event type "${def.type}" - used by both "${existing}" and "${collectionName}" collections`);
+		typeToCollection.set(def.type, collectionName);
+	}
+	const enhancedCollections = {};
+	for (const [name, collectionDef] of Object.entries(collections)) enhancedCollections[name] = {
+		...collectionDef,
+		...createCollectionHelpers(collectionDef.type, collectionDef.primaryKey, collectionDef.schema)
+	};
+	return enhancedCollections;
+}
+
+//#endregion
+Object.defineProperty(exports, 'MaterializedState', {
+  enumerable: true,
+  get: function () {
+    return MaterializedState;
+  }
+});
+Object.defineProperty(exports, 'createStateSchema', {
+  enumerable: true,
+  get: function () {
+    return createStateSchema;
+  }
+});
+Object.defineProperty(exports, 'isChangeEvent', {
+  enumerable: true,
+  get: function () {
+    return isChangeEvent;
+  }
+});
+Object.defineProperty(exports, 'isControlEvent', {
+  enumerable: true,
+  get: function () {
+    return isControlEvent;
+  }
+});

package/dist/src-VTyL9Eij.js

@@ -0,0 +1,203 @@
+//#region src/types.ts
+/**
+* Type guard to check if an event is a change event
+*/
+function isChangeEvent(event) {
+	return event != null && `operation` in event.headers;
+}
+/**
+* Type guard to check if an event is a control event
+*/
+function isControlEvent(event) {
+	return event != null && `control` in event.headers;
+}
+
+//#endregion
+//#region src/materialized-state.ts
+/**
+* MaterializedState maintains an in-memory view of state from change events.
+*
+* It organizes data by type, where each type contains a map of key -> value.
+* This supports multi-type streams where different entity types can coexist.
+*/
+var MaterializedState = class {
+	data;
+	constructor() {
+		this.data = new Map();
+	}
+	/**
+	* Apply a single change event to update the materialized state
+	*/
+	apply(event) {
+		const { type, key, value, headers } = event;
+		let typeMap = this.data.get(type);
+		if (!typeMap) {
+			typeMap = new Map();
+			this.data.set(type, typeMap);
+		}
+		switch (headers.operation) {
+			case `insert`:
+				typeMap.set(key, value);
+				break;
+			case `update`:
+				typeMap.set(key, value);
+				break;
+			case `upsert`:
+				typeMap.set(key, value);
+				break;
+			case `delete`:
+				typeMap.delete(key);
+				break;
+		}
+	}
+	/**
+	* Apply a batch of change events
+	*/
+	applyBatch(events) {
+		for (const event of events) this.apply(event);
+	}
+	/**
+	* Get a specific value by type and key
+	*/
+	get(type, key) {
+		const typeMap = this.data.get(type);
+		if (!typeMap) return void 0;
+		return typeMap.get(key);
+	}
+	/**
+	* Get all entries for a specific type
+	*/
+	getType(type) {
+		return this.data.get(type) || new Map();
+	}
+	/**
+	* Clear all state
+	*/
+	clear() {
+		this.data.clear();
+	}
+	/**
+	* Get the number of types in the state
+	*/
+	get typeCount() {
+		return this.data.size;
+	}
+	/**
+	* Get all type names
+	*/
+	get types() {
+		return Array.from(this.data.keys());
+	}
+};
+
+//#endregion
+//#region src/schema.ts
+/**
+* Reserved collection names that would collide with StreamDB properties
+* (collections are now namespaced, but we still prevent internal name collisions)
+*/
+const RESERVED_COLLECTION_NAMES = new Set([
+	`collections`,
+	`preload`,
+	`close`,
+	`utils`,
+	`actions`
+]);
+/**
+* Create helper functions for a collection
+*/
+function createCollectionHelpers(eventType, primaryKey, schema) {
+	return {
+		insert: ({ key, value, headers }) => {
+			const result = schema[`~standard`].validate(value);
+			if (`issues` in result) throw new Error(`Validation failed for ${eventType} insert: ${result.issues?.map((i) => i.message).join(`, `) ?? `Unknown validation error`}`);
+			const derived = value[primaryKey];
+			const finalKey = key ?? (derived != null && derived !== `` ? String(derived) : void 0);
+			if (finalKey == null || finalKey === ``) throw new Error(`Cannot create ${eventType} insert event: must provide either 'key' or a value with a non-empty '${primaryKey}' field`);
+			return {
+				type: eventType,
+				key: finalKey,
+				value,
+				headers: {
+					...headers,
+					operation: `insert`
+				}
+			};
+		},
+		update: ({ key, value, oldValue, headers }) => {
+			const result = schema[`~standard`].validate(value);
+			if (`issues` in result) throw new Error(`Validation failed for ${eventType} update: ${result.issues?.map((i) => i.message).join(`, `) ?? `Unknown validation error`}`);
+			if (oldValue !== void 0) {
+				const oldResult = schema[`~standard`].validate(oldValue);
+				if (`issues` in oldResult) throw new Error(`Validation failed for ${eventType} update (oldValue): ${oldResult.issues?.map((i) => i.message).join(`, `) ?? `Unknown validation error`}`);
+			}
+			const derived = value[primaryKey];
+			const finalKey = key ?? (derived != null && derived !== `` ? String(derived) : void 0);
+			if (finalKey == null || finalKey === ``) throw new Error(`Cannot create ${eventType} update event: must provide either 'key' or a value with a non-empty '${primaryKey}' field`);
+			return {
+				type: eventType,
+				key: finalKey,
+				value,
+				old_value: oldValue,
+				headers: {
+					...headers,
+					operation: `update`
+				}
+			};
+		},
+		delete: ({ key, oldValue, headers }) => {
+			if (oldValue !== void 0) {
+				const result = schema[`~standard`].validate(oldValue);
+				if (`issues` in result) throw new Error(`Validation failed for ${eventType} delete (oldValue): ${result.issues?.map((i) => i.message).join(`, `) ?? `Unknown validation error`}`);
+			}
+			const finalKey = key ?? (oldValue ? String(oldValue[primaryKey]) : void 0);
+			if (!finalKey) throw new Error(`Cannot create ${eventType} delete event: must provide either 'key' or 'oldValue' with a ${primaryKey} field`);
+			return {
+				type: eventType,
+				key: finalKey,
+				old_value: oldValue,
+				headers: {
+					...headers,
+					operation: `delete`
+				}
+			};
+		},
+		upsert: ({ key, value, headers }) => {
+			const result = schema[`~standard`].validate(value);
+			if (`issues` in result) throw new Error(`Validation failed for ${eventType} upsert: ${result.issues?.map((i) => i.message).join(`, `) ?? `Unknown validation error`}`);
+			const derived = value[primaryKey];
+			const finalKey = key ?? (derived != null && derived !== `` ? String(derived) : void 0);
+			if (finalKey == null || finalKey === ``) throw new Error(`Cannot create ${eventType} upsert event: must provide either 'key' or a value with a non-empty '${primaryKey}' field`);
+			return {
+				type: eventType,
+				key: finalKey,
+				value,
+				headers: {
+					...headers,
+					operation: `upsert`
+				}
+			};
+		}
+	};
+}
+/**
+* Create a state schema definition with typed collections and event helpers
+*/
+function createStateSchema(collections) {
+	for (const name of Object.keys(collections)) if (RESERVED_COLLECTION_NAMES.has(name)) throw new Error(`Reserved collection name "${name}" - this would collide with StreamDB properties (${Array.from(RESERVED_COLLECTION_NAMES).join(`, `)})`);
+	const typeToCollection = new Map();
+	for (const [collectionName, def] of Object.entries(collections)) {
+		const existing = typeToCollection.get(def.type);
+		if (existing) throw new Error(`Duplicate event type "${def.type}" - used by both "${existing}" and "${collectionName}" collections`);
+		typeToCollection.set(def.type, collectionName);
+	}
+	const enhancedCollections = {};
+	for (const [name, collectionDef] of Object.entries(collections)) enhancedCollections[name] = {
+		...collectionDef,
+		...createCollectionHelpers(collectionDef.type, collectionDef.primaryKey, collectionDef.schema)
+	};
+	return enhancedCollections;
+}
+
+//#endregion
+export { MaterializedState, createStateSchema, isChangeEvent, isControlEvent };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@durable-streams/state",
   "description": "State change event protocol for Durable Streams",
-  "version": "0.2.9",
+  "version": "0.3.1",
   "author": "Durable Stream contributors",
   "license": "Apache-2.0",
   "repository": {
@@ -33,6 +33,16 @@
         "default": "./dist/index.cjs"
       }
     },
+    "./db": {
+      "import": {
+        "types": "./dist/db.d.ts",
+        "default": "./dist/db.js"
+      },
+      "require": {
+        "types": "./dist/db.d.cts",
+        "default": "./dist/db.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
   "sideEffects": false,
@@ -50,13 +60,21 @@
   ],
   "dependencies": {
     "@standard-schema/spec": "^1.0.0",
-    "@tanstack/db": "^0.6.0",
     "@durable-streams/client": "0.2.6"
   },
+  "peerDependencies": {
+    "@tanstack/db": ">=0.6.0 <1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/db": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@tanstack/db": "0.6.0",
     "@tanstack/intent": "latest",
     "tsdown": "^0.9.0",
-    "@durable-streams/server": "0.3.5"
+    "@durable-streams/server": "0.3.7"
   },
   "engines": {
     "node": ">=18.0.0"

package/skills/stream-db/SKILL.md

@@ -28,7 +28,7 @@ optimistic actions, and transaction confirmation.
 ## Setup
 
 ```typescript
-import { createStreamDB, createStateSchema } from "@durable-streams/state"
+import { createStreamDB, createStateSchema } from "@durable-streams/state/db"
 import { DurableStream } from "@durable-streams/client"
 import { z } from "zod"
 
@@ -83,7 +83,7 @@ StreamDB collections are TanStack DB collections. Use framework adapters for rea
 
 ```typescript
 import { useLiveQuery } from "@tanstack/react-db"
-import { eq } from "@durable-streams/state"
+import { eq } from "@durable-streams/state/db"
 
 // List query — destructure { data } with a default empty array
 function UserList() {
@@ -111,7 +111,7 @@ function UserProfile({ userId }: { userId: string }) {
 ### Optimistic actions with server confirmation
 
 ```typescript
-import { createStreamDB, createStateSchema } from "@durable-streams/state"
+import { createStreamDB, createStateSchema } from "@durable-streams/state/db"
 import { z } from "zod"
 
 const schema = createStateSchema({

package/src/db.ts

@@ -0,0 +1,61 @@
+// `@durable-streams/state/db`: the full surface, including the reactive,
+// TanStack DB-backed StreamDB layer. Importing this entry pulls in @tanstack/db,
+// which is a peer dependency — consumers using this subpath must install it.
+//
+// It is a strict superset of the db-free main entry (`@durable-streams/state`),
+// so code that uses both `createStateSchema` and `createStreamDB` can import
+// everything from here.
+
+export * from "./index"
+
+// Reactive StreamDB layer
+export { createStreamDB, getStreamDBCollectionId } from "./stream-db"
+export type {
+  CreateStreamDBOptions,
+  StreamDB,
+  StreamDBMethods,
+  StreamDBUtils,
+  StreamDBWithActions,
+  ActionFactory,
+  ActionMap,
+  ActionDefinition,
+} from "./stream-db"
+
+// Re-export key types and utilities from @tanstack/db for convenience.
+// This ensures consumers can use the same module resolution for type compatibility.
+export type { Collection, SyncConfig } from "@tanstack/db"
+export {
+  createCollection,
+  createLiveQueryCollection,
+  createOptimisticAction,
+  createTransaction,
+  deepEquals,
+  localOnlyCollectionOptions,
+  queryOnce,
+  // Comparison operators
+  eq,
+  gt,
+  gte,
+  lt,
+  lte,
+  like,
+  ilike,
+  inArray,
+  // Logical operators
+  and,
+  or,
+  not,
+  // Null checking
+  isNull,
+  isUndefined,
+  // Aggregate functions
+  count,
+  sum,
+  avg,
+  min,
+  max,
+  // Includes/projection functions
+  concat,
+  coalesce,
+  toArray,
+} from "@tanstack/db"

package/src/index.ts

@@ -1,3 +1,11 @@
+// Main entry: the db-free surface of the state protocol.
+//
+// Everything exported here works without @tanstack/db installed — defining
+// schemas, constructing/validating change events, and materializing state
+// in-memory. The reactive, TanStack DB-backed StreamDB layer (createStreamDB,
+// live queries, optimistic actions) lives under the `@durable-streams/state/db`
+// subpath, which carries the `@tanstack/db` peer dependency.
+
 // Types
 export type {
   Operation,
@@ -11,66 +19,15 @@ export type {
 
 export { isChangeEvent, isControlEvent } from "./types"
 
-// Classes
+// In-memory materialization
 export { MaterializedState } from "./materialized-state"
 
-// Stream DB
-export {
-  createStreamDB,
-  createStateSchema,
-  getStreamDBCollectionId,
-} from "./stream-db"
+// Schema definition + event construction (producer side)
+export { createStateSchema } from "./schema"
 export type {
   CollectionDefinition,
   CollectionEventHelpers,
   CollectionWithHelpers,
   StreamStateDefinition,
   StateSchema,
-  CreateStreamDBOptions,
-  StreamDB,
-  StreamDBMethods,
-  StreamDBUtils,
-  StreamDBWithActions,
-  ActionFactory,
-  ActionMap,
-  ActionDefinition,
-} from "./stream-db"
-
-// Re-export key types and utilities from @tanstack/db for convenience
-// This ensures consumers can use the same module resolution for type compatibility
-export type { Collection, SyncConfig } from "@tanstack/db"
-export {
-  createCollection,
-  createLiveQueryCollection,
-  createOptimisticAction,
-  createTransaction,
-  deepEquals,
-  localOnlyCollectionOptions,
-  queryOnce,
-  // Comparison operators
-  eq,
-  gt,
-  gte,
-  lt,
-  lte,
-  like,
-  ilike,
-  inArray,
-  // Logical operators
-  and,
-  or,
-  not,
-  // Null checking
-  isNull,
-  isUndefined,
-  // Aggregate functions
-  count,
-  sum,
-  avg,
-  min,
-  max,
-  // Includes/projection functions
-  concat,
-  coalesce,
-  toArray,
-} from "@tanstack/db"
+} from "./schema"