@firtoz/db-helpers 2.1.0 → 2.2.0

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { CollectionUtils, ExternalSyncEvent, ExternalSyncHandler, ReceiveSyncDurableOp, SyncMessage } from './sync-types.js';
+export { MemoryCollection, createMemoryCollection, memoryCollectionOptions } from './memoryCollection.js';
+export { evaluateExpression, getExpressionValue } from './ir-evaluator.js';
+export { GenericBaseSyncConfig, GenericSyncBackend, GenericSyncFunctionResult, USE_DEDUPE, createGenericCollectionConfig, createGenericSyncFunction } from './generic-sync.js';
+export { DeferredDeleteMutation, DeferredUpdateMutation, DeferredWriteQueue } from './deferred-write-queue.js';
+import '@standard-schema/spec';
+import '@tanstack/db';

package/dist/index.js

@@ -0,0 +1,7 @@
+export { USE_DEDUPE, createGenericCollectionConfig, createGenericSyncFunction } from './chunk-72YXZ3BK.js';
+export { DeferredWriteQueue } from './chunk-E6ZONR5D.js';
+export { evaluateExpression, getExpressionValue } from './chunk-Y64WBRON.js';
+export { createMemoryCollection, memoryCollectionOptions } from './chunk-EIDXVFD3.js';
+import './chunk-HMLY7DHA.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/ir-evaluator.d.ts

@@ -0,0 +1,14 @@
+import { IR } from '@tanstack/db';
+
+/**
+ * Evaluates a TanStack DB IR expression against a plain object item.
+ * @internal Exported for testing and reuse by collection backends
+ */
+declare function evaluateExpression(expression: IR.BasicExpression, item: Record<string, unknown>): boolean;
+/**
+ * Gets the value from an IR expression by resolving refs and vals.
+ * @internal Exported for testing and reuse by collection backends
+ */
+declare function getExpressionValue(expression: IR.BasicExpression, item: Record<string, unknown>): any;
+
+export { evaluateExpression, getExpressionValue };

package/dist/ir-evaluator.js

@@ -0,0 +1,4 @@
+export { evaluateExpression, getExpressionValue } from './chunk-Y64WBRON.js';
+import './chunk-HMLY7DHA.js';
+//# sourceMappingURL=ir-evaluator.js.map
+//# sourceMappingURL=ir-evaluator.js.map

package/dist/ir-evaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"ir-evaluator.js"}

package/dist/memoryCollection.d.ts

@@ -0,0 +1,26 @@
+import { SyncMessage } from './sync-types.js';
+import { StandardSchemaV1 } from '@standard-schema/spec';
+import { CollectionConfig, InferSchemaOutput, Collection, InferSchemaInput } from '@tanstack/db';
+
+type MemoryCollectionConfig<TSchema extends StandardSchemaV1> = Omit<CollectionConfig<InferSchemaOutput<TSchema>, string | number, TSchema>, "onInsert" | "onUpdate" | "onDelete" | "sync" | "schema"> & {
+    schema: TSchema;
+    /** Called when a local mutation is written to the sync layer; use to broadcast to other peers. */
+    onBroadcast?: (changes: SyncMessage<InferSchemaOutput<TSchema>, string | number>[]) => void;
+};
+type MemoryUtils<TItem = unknown, TKey extends string | number = string | number> = {
+    truncate: () => Promise<void>;
+    /**
+     * Apply incoming sync messages without triggering onInsert/onUpdate/onDelete.
+     * Uses the sync layer (begin/write/commit) so state updates and subscribeChanges fire,
+     * but no rebroadcast occurs.
+     */
+    receiveSync: (messages: SyncMessage<TItem, TKey>[]) => Promise<void>;
+};
+declare function memoryCollectionOptions<TSchema extends StandardSchemaV1>(config: MemoryCollectionConfig<TSchema>): CollectionConfig<InferSchemaOutput<TSchema>, string | number, TSchema> & {
+    utils: MemoryUtils<InferSchemaOutput<TSchema>, string | number>;
+    schema: TSchema;
+};
+type MemoryCollection<TSchema extends StandardSchemaV1> = Collection<InferSchemaOutput<TSchema>, string | number, MemoryUtils<InferSchemaOutput<TSchema>, string | number>, TSchema, InferSchemaInput<TSchema>>;
+declare function createMemoryCollection<TSchema extends StandardSchemaV1>(config: MemoryCollectionConfig<TSchema>): MemoryCollection<TSchema>;
+
+export { type MemoryCollection, createMemoryCollection, memoryCollectionOptions };

package/dist/memoryCollection.js

@@ -0,0 +1,4 @@
+export { createMemoryCollection, memoryCollectionOptions } from './chunk-EIDXVFD3.js';
+import './chunk-HMLY7DHA.js';
+//# sourceMappingURL=memoryCollection.js.map
+//# sourceMappingURL=memoryCollection.js.map

package/dist/memoryCollection.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"memoryCollection.js"}

package/dist/sync-types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Generic collection sync types. Used by memory, IndexedDB, SQLite, and other
+ * collection backends for a unified sync protocol.
+ */
+/**
+ * Canonical per-mutation sync message. Use for broadcast and receive across all collection types.
+ */
+type SyncMessage<T = unknown, TKey extends string | number = string | number> = {
+    type: "insert";
+    value: T;
+} | {
+    type: "update";
+    value: T;
+    previousValue: T;
+} | {
+    type: "delete";
+    key: TKey;
+} | {
+    type: "truncate";
+};
+/**
+ * Normalized durable ops for a {@link SyncMessage} batch. SQLite-style backends can implement
+ * `GenericSyncBackend.applyReceiveSyncDurableWrites` to persist the whole batch in one store
+ * transaction instead of one transaction per message.
+ */
+type ReceiveSyncDurableOp<TItem extends object> = {
+    type: "insert";
+    value: TItem;
+} | {
+    type: "update";
+    key: string;
+    changes: Partial<TItem>;
+    original: TItem;
+} | {
+    type: "delete";
+    key: string;
+} | {
+    type: "truncate";
+};
+/**
+ * External sync event (batched). Used internally by the sync layer.
+ */
+type ExternalSyncEvent<T> = {
+    type: "insert";
+    items: T[];
+} | {
+    type: "update";
+    items: T[];
+} | {
+    type: "delete";
+    items: T[];
+} | {
+    type: "truncate";
+};
+/**
+ * Handler for external sync events (internal use).
+ */
+type ExternalSyncHandler<T> = (event: ExternalSyncEvent<T>) => void;
+/**
+ * Collection utils: truncate and receiveSync (canonical sync protocol).
+ */
+interface CollectionUtils<T = unknown> {
+    /**
+     * Clear all data from the store (truncate).
+     * This clears the backend store and updates the local reactive store.
+     */
+    truncate: () => Promise<void>;
+    /**
+     * Apply incoming sync messages without triggering mutation handlers.
+     * Use the same SyncMessage[] shape for memory and backend collections.
+     */
+    receiveSync: (messages: SyncMessage<T>[]) => Promise<void>;
+}
+
+export type { CollectionUtils, ExternalSyncEvent, ExternalSyncHandler, ReceiveSyncDurableOp, SyncMessage };

package/dist/sync-types.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=sync-types.js.map
+//# sourceMappingURL=sync-types.js.map

package/dist/sync-types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"sync-types.js"}

package/package.json

@@ -1,23 +1,28 @@
 {
 	"name": "@firtoz/db-helpers",
-	"version": "2.1.0",
+	"version": "2.2.0",
 	"description": "TanStack DB helpers and utilities",
-	"main": "./src/index.ts",
-	"module": "./src/index.ts",
-	"types": "./src/index.ts",
+	"type": "module",
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
 	"exports": {
 		".": {
-			"types": "./src/index.ts",
-			"import": "./src/index.ts",
-			"require": "./src/index.ts"
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
 		}
 	},
 	"files": [
+		"dist/**/*.js",
+		"dist/**/*.js.map",
+		"dist/**/*.d.ts",
 		"src/**/*.ts",
 		"!src/**/*.test.ts",
 		"README.md"
 	],
 	"scripts": {
+		"build": "tsup",
+		"prepack": "bun run build",
 		"typecheck": "tsgo --noEmit -p ./tsconfig.json",
 		"test": "bun test",
 		"lint": "biome check --write src",
@@ -49,15 +54,15 @@
 	},
 	"peerDependencies": {
 		"@standard-schema/spec": ">=1.1.0",
-		"@tanstack/db": ">=0.6.1"
+		"@tanstack/db": ">=0.6.3"
 	},
 	"devDependencies": {
 		"@standard-schema/spec": "^1.1.0",
-		"@tanstack/db": "^0.6.1",
+		"@tanstack/db": "^0.6.4",
 		"bun-types": "^1.3.11",
 		"zod": "^4.3.6"
 	},
 	"dependencies": {
-		"@firtoz/maybe-error": "^1.5.2"
+		"@firtoz/maybe-error": "^1.6.0"
 	}
 }

package/src/generic-sync.ts

@@ -14,13 +14,12 @@ import type {
 	SyncMode,
 	LoadSubsetOptions,
 } from "@tanstack/db";
-import { DeduplicatedLoadSubset } from "@tanstack/db";
+import { BasicIndex, DeduplicatedLoadSubset } from "@tanstack/db";
 
-// WORKAROUND: DeduplicatedLoadSubset has a bug where toggling queries (e.g., isNull/isNotNull)
-// creates invalid expressions like not(or(isNull(...), not(isNull(...))))
-// See: https://github.com/TanStack/db/issues/828
-// TODO: Re-enable once the bug is fixed
-export const USE_DEDUPE = false as boolean;
+// DeduplicatedLoadSubset dedupes overlapping loadSubset calls. Previously disabled for TanStack/db#828
+// (invalid OR expressions when toggling isNull/isNotNull). Re-enabled with @tanstack/db 0.6.4; if
+// regressions appear, set back to false and add a regression test.
+export const USE_DEDUPE = true as boolean;
 
 /**
  * Base configuration for sync lifecycle management (generic, no Drizzle dependency).
@@ -646,6 +645,10 @@ export function createGenericCollectionConfig<
 		onUpdate: config.onUpdate ?? config.syncResult.onUpdate,
 		onDelete: config.onDelete ?? config.syncResult.onDelete,
 		syncMode: config.syncMode,
+		// TanStack DB 0.6+: indexing is opt-in; eager BasicIndex restores pre-0.6 behavior for
+		// orderBy/limit live queries (playground pagination, usePredicateFilteredRows, etc.).
+		defaultIndexType: BasicIndex,
+		autoIndex: "eager",
 		utils: config.syncResult.utils as CollectionUtils<
 			InferSchemaOutput<TSchema>
 		>,