@firtoz/drizzle-utils 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,82 @@
+# @firtoz/drizzle-utils
+
+## 0.1.0
+
+### Minor Changes
+
+- [#22](https://github.com/firtoz/fullstack-toolkit/pull/22) [`05e88e7`](https://github.com/firtoz/fullstack-toolkit/commit/05e88e775f262488d1da2b579eadd560cee2eba9) Thanks [@firtoz](https://github.com/firtoz)! - Initial release of `@firtoz/drizzle-utils` - Shared utilities and types for Drizzle ORM-based packages.
+
+  > **⚠️ Early WIP Notice:** This package is in very early development and is **not production-ready**. It is TypeScript-only and may have breaking changes. While I (the maintainer) have limited time, I'm open to PRs for features, bug fixes, or additional support (like JS builds). Please feel free to try it out and contribute! See [CONTRIBUTING.md](../../CONTRIBUTING.md) for details.
+
+  ## Features
+
+  ### Syncable Table Builder
+
+  - **`syncableTable`** - Creates SQLite tables with automatic timestamp tracking
+    - Auto-generates UUID primary keys with type branding
+    - Includes `id`, `createdAt`, `updatedAt`, and `deletedAt` columns
+    - Validates that default values are compatible with IndexedDB (no SQL expressions)
+    - Full TypeScript type safety with branded IDs
+
+  ### Column Helpers
+
+  - **`idColumn`** - Branded text primary key column
+  - **`createdAtColumn`** - Integer timestamp with automatic default (now)
+  - **`updatedAtColumn`** - Integer timestamp with automatic default (now)
+  - **`deletedAtColumn`** - Nullable integer timestamp for soft deletes
+
+  ### Type Utilities
+
+  - **Branded IDs** - Type-safe string IDs with table-specific branding
+    - `TableId<TTableName>` - Table-specific branded ID type
+    - `IdOf<TTable>` - Extract ID type from a table
+    - `makeId()` - Safely create branded IDs
+  - **Schema Helpers** - Type-safe Valibot schema inference
+    - `SelectSchema<TTable>` - Infer select schema from table
+    - `InsertSchema<TTable>` - Infer insert schema from table
+
+  ### Migration Types
+
+  Shared TypeScript types for Drizzle migrations across different database backends:
+
+  - **Journal Types** - `Journal`, `JournalEntry`
+  - **Schema Definition Types** - `TableDefinition`, `ColumnDefinition`, `IndexDefinition`, `ForeignKeyDefinition`, `ViewDefinition`, `EnumDefinition`, etc.
+  - **Snapshot Types** - `Snapshot`, `SnapshotMeta`, `SnapshotInternal`
+
+  These types enable consistent migration handling in both IndexedDB and SQLite WASM packages.
+
+  ## Example
+
+  ```typescript
+  import { syncableTable, idColumn } from "@firtoz/drizzle-utils";
+  import { text } from "drizzle-orm/sqlite-core";
+
+  // Create a table with automatic timestamp tracking
+  const todoTable = syncableTable("todos", {
+    title: text("title").notNull(),
+    completed: integer("completed", { mode: "boolean" })
+      .notNull()
+      .default(false),
+  });
+
+  // The table automatically includes:
+  // - id: TableId<"todos"> (UUID primary key)
+  // - createdAt: Date (auto-set on insert)
+  // - updatedAt: Date (auto-set on insert/update)
+  // - deletedAt: Date | null (for soft deletes)
+
+  type Todo = typeof todoTable.$inferSelect;
+  // {
+  //   id: TableId<"todos">;
+  //   title: string;
+  //   completed: boolean;
+  //   createdAt: Date;
+  //   updatedAt: Date;
+  //   deletedAt: Date | null;
+  // }
+  ```
+
+  ## Dependencies
+
+  - `drizzle-orm` (peer dependency)
+  - `drizzle-valibot` (peer dependency)

package/README.md

@@ -0,0 +1,270 @@
+# @firtoz/drizzle-utils
+
+Shared utilities and types for Drizzle ORM-based packages. Provides type-safe table builders with automatic timestamp tracking, branded IDs, and common migration types.
+
+> **⚠️ Early WIP Notice:** This package is in very early development and is **not production-ready**. It is TypeScript-only and may have breaking changes. While I (the maintainer) have limited time, I'm open to PRs for features, bug fixes, or additional support (like JS builds). Please feel free to try it out and contribute! See [CONTRIBUTING.md](../../CONTRIBUTING.md) for details.
+
+## Installation
+
+```bash
+npm install @firtoz/drizzle-utils drizzle-orm drizzle-valibot
+```
+
+## Features
+
+### 🏗️ Syncable Table Builder
+
+Create SQLite tables with automatic timestamp tracking and UUID primary keys:
+
+```typescript
+import { syncableTable } from "@firtoz/drizzle-utils";
+import { text, integer } from "drizzle-orm/sqlite-core";
+
+const todoTable = syncableTable("todos", {
+  title: text("title").notNull(),
+  completed: integer("completed", { mode: "boolean" }).notNull().default(false),
+  description: text("description"),
+});
+
+// Automatically includes:
+// - id: TableId<"todos"> (UUID primary key)
+// - createdAt: Date (auto-set on insert)
+// - updatedAt: Date (auto-set on update)
+// - deletedAt: Date | null (for soft deletes)
+
+type Todo = typeof todoTable.$inferSelect;
+// {
+//   id: TableId<"todos">;
+//   title: string;
+//   completed: boolean;
+//   description: string | null;
+//   createdAt: Date;
+//   updatedAt: Date;
+//   deletedAt: Date | null;
+// }
+```
+
+### 🏷️ Branded ID Types
+
+Type-safe IDs with table-specific branding prevent mixing IDs from different tables:
+
+```typescript
+import { makeId, type IdOf } from "@firtoz/drizzle-utils";
+
+const todoId = makeId(todoTable, "123e4567-e89b-12d3-a456-426614174000");
+const userId = makeId(userTable, "123e4567-e89b-12d3-a456-426614174000");
+
+// TypeScript prevents mixing different table IDs
+function getTodo(id: IdOf<typeof todoTable>) { /* ... */ }
+
+getTodo(todoId);  // ✅ OK
+getTodo(userId);  // ❌ Type error - wrong table!
+```
+
+### 📋 Column Helpers
+
+Individual column builders for custom table definitions:
+
+```typescript
+import { 
+  idColumn, 
+  createdAtColumn, 
+  updatedAtColumn, 
+  deletedAtColumn 
+} from "@firtoz/drizzle-utils";
+
+// Use in custom table definitions
+const customTable = sqliteTable("custom", {
+  id: idColumn,
+  name: text("name").notNull(),
+  createdAt: createdAtColumn,
+  updatedAt: updatedAtColumn,
+  deletedAt: deletedAtColumn,
+});
+```
+
+### 🔄 Migration Types
+
+Shared TypeScript types for Drizzle migrations across IndexedDB and SQLite:
+
+```typescript
+import type { 
+  Journal, 
+  JournalEntry,
+  Snapshot,
+  TableDefinition,
+  ColumnDefinition,
+  IndexDefinition
+} from "@firtoz/drizzle-utils";
+
+// Use these types for custom migration logic
+function applyMigration(snapshot: Snapshot) {
+  for (const [tableName, table] of Object.entries(snapshot.tables)) {
+    const tableDef: TableDefinition = table;
+    // ... migration logic
+  }
+}
+```
+
+### 📝 Schema Type Helpers
+
+Type-safe Valibot schema inference:
+
+```typescript
+import { type SelectSchema, type InsertSchema } from "@firtoz/drizzle-utils";
+
+type TodoSelect = SelectSchema<typeof todoTable>;
+type TodoInsert = InsertSchema<typeof todoTable>;
+
+// Use with Valibot for runtime validation
+import { parse } from "valibot";
+import { createSelectSchema, createInsertSchema } from "drizzle-valibot";
+
+const selectSchema = createSelectSchema(todoTable);
+const insertSchema = createInsertSchema(todoTable);
+
+const validTodo = parse(selectSchema, data);
+```
+
+## API Reference
+
+### Table Builders
+
+#### `syncableTable(name, columns, extraConfig?)`
+
+Creates a SQLite table with automatic timestamp tracking.
+
+**Parameters:**
+- `name: string` - Table name
+- `columns: Record<string, SQLiteColumnBuilder>` - Column definitions (cannot use `id`, `createdAt`, `updatedAt`, or `deletedAt` as keys)
+- `extraConfig?: (self) => SQLiteTableExtraConfigValue[]` - Optional indexes and constraints
+
+**Returns:** SQLite table with id, createdAt, updatedAt, deletedAt columns
+
+**Validation:**
+- Ensures default values are compatible with IndexedDB (no SQL expressions)
+- Throws error if SQL expressions are used as default values
+
+### Column Helpers
+
+#### `idColumn`
+
+Text column configured as primary key with branded UUID type.
+
+#### `createdAtColumn`
+
+Integer timestamp column (mode: "timestamp") with automatic default (current date).
+
+#### `updatedAtColumn`
+
+Integer timestamp column (mode: "timestamp") with automatic default (current date).
+
+#### `deletedAtColumn`
+
+Nullable integer timestamp column (mode: "timestamp") for soft deletes.
+
+### Type Utilities
+
+#### `Branded<T, Brand>`
+
+Creates a branded type for better type safety.
+
+#### `TableId<TTableName>`
+
+Table-specific branded ID type with table name in the brand.
+
+#### `IdOf<TTable>`
+
+Extracts the ID type from a Drizzle table.
+
+#### `makeId<TTable>(table, value)`
+
+Safely creates a branded ID for a specific table.
+
+#### `SelectSchema<TTable>`
+
+Infers the Valibot select schema type from a Drizzle table.
+
+#### `InsertSchema<TTable>`
+
+Infers the Valibot insert schema type from a Drizzle table.
+
+### Migration Types
+
+Comprehensive types for database migrations:
+
+- `Journal` - Migration journal with version and entries
+- `JournalEntry` - Individual migration record
+- `Snapshot` - Complete database schema snapshot
+- `TableDefinition` - Table structure definition
+- `ColumnDefinition` - Column configuration
+- `IndexDefinition` - Index configuration
+- `ForeignKeyDefinition` - Foreign key constraint
+- `ViewDefinition` - Database view definition
+- `EnumDefinition` - Enum type definition
+
+## Best Practices
+
+### 1. Use syncableTable for Data Tables
+
+Always use `syncableTable` for tables that need timestamp tracking:
+
+```typescript
+// ✅ Good - automatic timestamps
+const todoTable = syncableTable("todos", {
+  title: text("title").notNull(),
+});
+
+// ❌ Bad - manual timestamp management
+const todoTable = sqliteTable("todos", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  createdAt: integer("createdAt", { mode: "timestamp" }),
+  // ... repetitive boilerplate
+});
+```
+
+### 2. Leverage Branded IDs
+
+Use branded IDs to prevent mixing IDs from different tables:
+
+```typescript
+type TodoId = IdOf<typeof todoTable>;
+type UserId = IdOf<typeof userTable>;
+
+function assignTodo(todoId: TodoId, userId: UserId) {
+  // Type safety ensures correct ID types are used
+}
+```
+
+### 3. Avoid SQL Expressions in Defaults
+
+The `syncableTable` validates that default values work with IndexedDB:
+
+```typescript
+// ✅ Good - JavaScript default
+const table = syncableTable("table", {
+  status: text("status").default("pending"),
+  count: integer("count").default(0),
+});
+
+// ❌ Bad - SQL expression (will throw error)
+const table = syncableTable("table", {
+  status: text("status").default(sql`'pending'`),  // Error!
+});
+```
+
+## Integration
+
+This package is used by:
+- `@firtoz/drizzle-indexeddb` - IndexedDB migrations
+- `@firtoz/drizzle-sqlite-wasm` - SQLite WASM integration
+
+## License
+
+MIT
+
+## Author
+
+Firtina Ozbalikchi <firtoz@github.com>
+

package/package.json

@@ -0,0 +1,67 @@
+{
+	"name": "@firtoz/drizzle-utils",
+	"version": "0.1.0",
+	"description": "Shared utilities and types for Drizzle-based packages",
+	"main": "./src/index.ts",
+	"module": "./src/index.ts",
+	"types": "./src/index.ts",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"import": "./src/index.ts",
+			"require": "./src/index.ts"
+		},
+		"./*": {
+			"types": "./src/*.ts",
+			"import": "./src/*.ts",
+			"require": "./src/*.ts"
+		}
+	},
+	"files": [
+		"src/**/*.ts",
+		"!src/**/*.test.ts",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"scripts": {
+		"typecheck": "tsc --noEmit -p ./tsconfig.json",
+		"lint": "biome check --write src",
+		"lint:ci": "biome ci src",
+		"format": "biome format src --write",
+		"test": "bun test --pass-with-no-tests",
+		"test:watch": "bun test --watch"
+	},
+	"keywords": [
+		"typescript",
+		"drizzle",
+		"utils"
+	],
+	"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/drizzle-utils"
+	},
+	"bugs": {
+		"url": "https://github.com/firtoz/fullstack-toolkit/issues"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"peerDependencies": {
+		"@tanstack/db": "^0.5.0",
+		"drizzle-orm": "^0.44.7",
+		"drizzle-valibot": "^0.4.2"
+	},
+	"devDependencies": {
+		"@tanstack/db": "^0.5.0",
+		"drizzle-orm": "^0.44.7",
+		"drizzle-valibot": "^0.4.2"
+	}
+}

package/src/collection-utils.ts

@@ -0,0 +1,76 @@
+import type { Table } from "drizzle-orm";
+import type { BuildSchema } from "drizzle-valibot";
+import type { Collection, UtilsRecord } from "@tanstack/db";
+
+/**
+ * Utility type for branded IDs
+ */
+export type Branded<T, Brand> = T & { __brand: Brand };
+
+export type TableId<TTableName extends string> = Branded<
+	string,
+	`${TTableName}_id`
+>;
+
+/**
+ * Utility type to extract the ID type from a table
+ */
+export type IdOf<TTable extends Table> = TTable extends {
+	$inferSelect: { id: infer TId extends string | number };
+}
+	? TId
+	: string | number;
+
+/**
+ * Utility function to safely create branded IDs
+ */
+export function makeId<TTable extends Table>(
+	_table: TTable,
+	value: string,
+): IdOf<TTable> {
+	return value as IdOf<TTable>;
+}
+
+/**
+ * Select schema type helper
+ */
+export type SelectSchema<TTable extends Table> = BuildSchema<
+	"select",
+	TTable["_"]["columns"],
+	undefined
+>;
+
+/**
+ * Insert schema type helper
+ */
+export type InsertSchema<TTable extends Table> = BuildSchema<
+	"insert",
+	TTable["_"]["columns"],
+	undefined
+>;
+
+/**
+ * Helper type to get the table from schema by name
+ */
+export type GetTableFromSchema<
+	TSchema extends Record<string, unknown>,
+	TTableName extends keyof TSchema,
+> = TSchema[TTableName] extends Table ? TSchema[TTableName] : never;
+
+/**
+ * Helper type to infer the collection type from table
+ * This provides proper typing for Collection insert/update operations
+ */
+export type InferCollectionFromTable<TTable extends Table> = Collection<
+	TTable["$inferSelect"],
+	IdOf<TTable>,
+	UtilsRecord,
+	SelectSchema<TTable>,
+	Omit<
+		TTable["$inferInsert"],
+		"id"
+		// "createdAt" | "updatedAt" | "deletedAt" | "id"
+	> & {
+		id?: IdOf<TTable>;
+	}
+>;

package/src/index.ts

@@ -0,0 +1,38 @@
+export type {
+	JournalEntry,
+	Journal,
+	SqliteColumnType,
+	ColumnDefinition,
+	IndexDefinition,
+	ForeignKeyDefinition,
+	CompositePrimaryKeyDefinition,
+	UniqueConstraintDefinition,
+	CheckConstraintDefinition,
+	TableDefinition,
+	ViewDefinition,
+	EnumDefinition,
+	SnapshotMeta,
+	SnapshotInternal,
+	Snapshot,
+} from "./types";
+
+export type {
+	Branded,
+	TableId,
+	IdOf,
+	SelectSchema,
+	InsertSchema,
+	GetTableFromSchema,
+	InferCollectionFromTable,
+} from "./collection-utils";
+
+export { makeId } from "./collection-utils";
+
+export {
+	createdAtColumn,
+	updatedAtColumn,
+	deletedAtColumn,
+	syncableTable,
+} from "./syncableTable";
+
+export type { TableWithRequiredFields } from "./syncableTable";

package/src/syncableTable.ts

@@ -0,0 +1,108 @@
+import {
+	integer,
+	text,
+	sqliteTable,
+	type SQLiteColumnBuilderBase,
+	type TableConfig,
+	type SQLiteTableExtraConfigValue,
+	type SQLiteTableWithColumns,
+} from "drizzle-orm/sqlite-core";
+import { type BuildColumns, getTableColumns, SQL } from "drizzle-orm";
+import type { TableId } from "./collection-utils";
+
+const createTableIdColumn = <TTableName extends string>() =>
+	text("id")
+		.primaryKey()
+		.$type<TableId<TTableName>>()
+		.$defaultFn(() => {
+			return crypto.randomUUID() as TableId<TTableName>;
+		});
+
+// Use unixepoch with 'subsec' modifier for millisecond precision timestamps
+export const createdAtColumn = integer("createdAt", { mode: "timestamp_ms" })
+	.$defaultFn(() => new Date())
+	.notNull();
+
+export const updatedAtColumn = integer("updatedAt", { mode: "timestamp_ms" })
+	.$defaultFn(() => new Date())
+	.notNull();
+
+export const deletedAtColumn = integer("deletedAt", {
+	mode: "timestamp_ms",
+});
+
+export const syncableTable = <
+	TTableName extends string,
+	TColumns extends Record<string, SQLiteColumnBuilderBase> & {
+		id?: never;
+		createdAt?: never;
+		updatedAt?: never;
+		deletedAt?: never;
+	},
+>(
+	tableName: TTableName,
+	columns: TColumns,
+	extraConfig?: (
+		self: BuildColumns<
+			TTableName,
+			Omit<TColumns, "id" | "createdAt" | "updatedAt" | "deletedAt"> & {
+				id: ReturnType<typeof createTableIdColumn<TTableName>>;
+				createdAt: typeof createdAtColumn;
+				updatedAt: typeof updatedAtColumn;
+				deletedAt: typeof deletedAtColumn;
+			},
+			"sqlite"
+		>,
+	) => SQLiteTableExtraConfigValue[],
+) => {
+	const tableIdColumn = createTableIdColumn<TTableName>();
+	const table = sqliteTable(
+		tableName,
+		{
+			id: tableIdColumn,
+			createdAt: createdAtColumn,
+			updatedAt: updatedAtColumn,
+			deletedAt: deletedAtColumn,
+			...columns,
+		},
+		extraConfig,
+	);
+
+	const tableColumns = getTableColumns(table);
+
+	// console.log("table:", table);
+
+	for (const columnName in tableColumns) {
+		const column = tableColumns[columnName];
+
+		let defaultValue: unknown | undefined;
+		if (column.defaultFn) {
+			defaultValue = column.defaultFn();
+		} else if (column.default !== undefined) {
+			defaultValue = column.default;
+		}
+
+		if (defaultValue instanceof SQL) {
+			throw new Error(
+				`Default value for column ${tableName}.${columnName} is a SQL expression, which is not supported for IndexedDB.\n\nYou can use a default value or a default function instead.`,
+			);
+		}
+	}
+
+	return table;
+};
+
+export type TableWithRequiredFields = SQLiteTableWithColumns<
+	Pick<TableConfig, "name" | "schema" | "dialect"> & {
+		columns: BuildColumns<
+			string,
+			{
+				id: ReturnType<typeof createTableIdColumn<string>>;
+				createdAt: typeof createdAtColumn;
+				updatedAt: typeof updatedAtColumn;
+				deletedAt: typeof deletedAtColumn;
+			},
+			"sqlite"
+		>;
+	}
+>;

package/src/types.ts

@@ -0,0 +1,108 @@
+// Shared types for Drizzle migrations across different database backends
+
+// ============================================================================
+// Journal Types
+// ============================================================================
+
+export interface JournalEntry {
+	idx: number;
+	version: string;
+	when: number;
+	tag: string;
+	breakpoints: boolean;
+}
+
+export interface Journal {
+	version: string;
+	dialect: string;
+	entries: JournalEntry[];
+}
+
+// ============================================================================
+// Schema Definition Types
+// ============================================================================
+
+export type SqliteColumnType = "text" | "integer" | "real" | "blob" | "numeric";
+
+export interface ColumnDefinition {
+	name: string;
+	type: SqliteColumnType | string;
+	primaryKey: boolean;
+	notNull: boolean;
+	autoincrement: boolean;
+	default?: string | number | boolean | null;
+}
+
+export interface IndexDefinition {
+	name: string;
+	columns: string[];
+	isUnique: boolean;
+}
+
+export interface ForeignKeyDefinition {
+	name: string;
+	tableFrom: string;
+	tableTo: string;
+	columnsFrom: string[];
+	columnsTo: string[];
+	onDelete?: "cascade" | "set null" | "set default" | "restrict" | "no action";
+	onUpdate?: "cascade" | "set null" | "set default" | "restrict" | "no action";
+}
+
+export interface CompositePrimaryKeyDefinition {
+	name: string;
+	columns: string[];
+}
+
+export interface UniqueConstraintDefinition {
+	name: string;
+	columns: string[];
+}
+
+export interface CheckConstraintDefinition {
+	name: string;
+	value: string;
+}
+
+export interface TableDefinition {
+	name: string;
+	columns: Record<string, ColumnDefinition>;
+	indexes: Record<string, IndexDefinition>;
+	foreignKeys: Record<string, ForeignKeyDefinition>;
+	compositePrimaryKeys: Record<string, CompositePrimaryKeyDefinition>;
+	uniqueConstraints: Record<string, UniqueConstraintDefinition>;
+	checkConstraints: Record<string, CheckConstraintDefinition>;
+}
+
+export interface ViewDefinition {
+	name: string;
+	query: string;
+	columns: Record<string, { name: string; type: string }>;
+}
+
+export interface EnumDefinition {
+	name: string;
+	values: string[];
+}
+
+export interface SnapshotMeta {
+	schemas: Record<string, unknown>;
+	tables: Record<string, unknown>;
+	columns: Record<string, string>; // Old column name -> new column name
+}
+
+export interface SnapshotInternal {
+	indexes: Record<string, unknown>;
+}
+
+export interface Snapshot {
+	version: string;
+	dialect: string;
+	id: string;
+	prevId: string;
+	tables: Record<string, TableDefinition>;
+	views: Record<string, ViewDefinition>;
+	enums: Record<string, EnumDefinition>;
+	_meta: SnapshotMeta;
+	internal: SnapshotInternal;
+}