@firtoz/db-helpers 0.1.0

package/README.md

@@ -0,0 +1,34 @@
+# @firtoz/db-helpers
+
+TanStack DB helpers and utilities. TypeScript-only, no build step—consume source directly.
+
+This package is a small collection of helpers for [@tanstack/db](https://tanstack.com/db). More utilities will be added over time.
+
+## Current helpers
+
+- **Memory collection** – In-memory TanStack DB collection with sync adapter and `truncate` utility. Useful for tests and ephemeral state.
+
+## Installation
+
+```bash
+bun add @firtoz/db-helpers
+# or npm/pnpm/yarn
+```
+
+Peer dependencies: `@tanstack/db` and `@standard-schema/spec`.
+
+## Usage
+
+```ts
+import {
+  createMemoryCollection,
+  memoryCollectionOptions,
+  type MemoryCollection,
+} from "@firtoz/db-helpers";
+```
+
+See [@tanstack/db](https://tanstack.com/db) docs for collection usage.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,57 @@
+{
+	"name": "@firtoz/db-helpers",
+	"version": "0.1.0",
+	"description": "TanStack DB helpers and utilities",
+	"main": "./src/index.ts",
+	"module": "./src/index.ts",
+	"types": "./src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"import": "./src/index.ts",
+			"require": "./src/index.ts"
+		}
+	},
+	"files": [
+		"src/**/*.ts",
+		"!src/**/*.test.ts",
+		"README.md"
+	],
+	"scripts": {
+		"typecheck": "tsc --noEmit -p ./tsconfig.json",
+		"lint": "biome check --write src",
+		"lint:ci": "biome ci src",
+		"format": "biome format src --write"
+	},
+	"keywords": [
+		"typescript",
+		"tanstack",
+		"tanstack-db",
+		"db-helpers"
+	],
+	"author": "Firtina Ozbalikchi <firtoz@github.com>",
+	"license": "MIT",
+	"homepage": "https://github.com/firtoz/fullstack-toolkit#readme",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/firtoz/fullstack-toolkit.git",
+		"directory": "packages/db-helpers"
+	},
+	"bugs": {
+		"url": "https://github.com/firtoz/fullstack-toolkit/issues"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"peerDependencies": {
+		"@standard-schema/spec": ">=1.1.0",
+		"@tanstack/db": ">=0.5.25"
+	},
+	"devDependencies": {
+		"@standard-schema/spec": "^1.1.0",
+		"@tanstack/db": "^0.5.25"
+	}
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export {
+	createMemoryCollection,
+	memoryCollectionOptions,
+	type MemoryCollection,
+} from "./memoryCollection";

package/src/memoryCollection.ts

@@ -0,0 +1,124 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import {
+	type Collection,
+	type CollectionConfig,
+	createCollection,
+	type DeleteMutationFnParams,
+	type InferSchemaInput,
+	type InferSchemaOutput,
+	type InsertMutationFnParams,
+	type SyncConfig,
+	type UpdateMutationFnParams,
+} from "@tanstack/db";
+
+type MemoryCollectionConfig<TSchema extends StandardSchemaV1> = Omit<
+	CollectionConfig<InferSchemaOutput<TSchema>, string | number, TSchema>,
+	"onInsert" | "onUpdate" | "onDelete" | "sync" | "schema"
+> & {
+	schema: TSchema;
+};
+
+type MemoryUtils = {
+	truncate: () => Promise<void>;
+};
+
+export function memoryCollectionOptions<TSchema extends StandardSchemaV1>(
+	config: MemoryCollectionConfig<TSchema>,
+): CollectionConfig<InferSchemaOutput<TSchema>, string | number, TSchema> & {
+	utils: MemoryUtils;
+	schema: TSchema;
+} {
+	type TItem = InferSchemaOutput<TSchema>;
+	let syncParams: Parameters<SyncConfig<TItem>["sync"]>[0] | null = null;
+
+	const sync: SyncConfig<TItem>["sync"] = (params) => {
+		syncParams = params;
+
+		params.markReady();
+
+		// Return cleanup function
+		return () => {};
+	};
+
+	// All mutation handlers use the same transaction sender
+	const onInsert = async (params: InsertMutationFnParams<TItem>) => {
+		if (!syncParams) {
+			throw new Error("Sync parameters not initialized");
+		}
+		syncParams.begin();
+		for (const mutation of params.transaction.mutations) {
+			syncParams.write({
+				type: "insert",
+				value: mutation.modified,
+			});
+		}
+		syncParams.commit();
+	};
+
+	const onUpdate = async (params: UpdateMutationFnParams<TItem>) => {
+		if (!syncParams) {
+			throw new Error("Sync parameters not initialized");
+		}
+		syncParams.begin();
+		for (const mutation of params.transaction.mutations) {
+			syncParams.write({
+				type: "update",
+				value: mutation.modified,
+				previousValue: mutation.original,
+			});
+		}
+		syncParams.commit();
+	};
+
+	const onDelete = async (params: DeleteMutationFnParams<TItem>) => {
+		if (!syncParams) {
+			throw new Error("Sync parameters not initialized");
+		}
+		syncParams.begin();
+		for (const mutation of params.transaction.mutations) {
+			syncParams.write({
+				type: "delete",
+				key: mutation.key,
+			});
+		}
+		syncParams?.commit();
+	};
+
+	const truncate = async () => {
+		if (!syncParams) {
+			throw new Error("Sync parameters not initialized");
+		}
+		syncParams.begin();
+		syncParams.truncate();
+		syncParams.commit();
+	};
+
+	return {
+		id: config.id,
+		schema: config.schema,
+		getKey: config.getKey,
+		sync: { sync },
+		onInsert,
+		onUpdate,
+		onDelete,
+		utils: {
+			truncate,
+		},
+	};
+}
+
+export type MemoryCollection<TSchema extends StandardSchemaV1> = Collection<
+	InferSchemaOutput<TSchema>,
+	string | number,
+	MemoryUtils,
+	TSchema,
+	InferSchemaInput<TSchema>
+>;
+
+export function createMemoryCollection<TSchema extends StandardSchemaV1>(
+	config: MemoryCollectionConfig<TSchema>,
+): MemoryCollection<TSchema> {
+	return createCollection(
+		memoryCollectionOptions(config),
+	) as MemoryCollection<TSchema>;
+}