@lobomfz/db 0.2.0 → 0.2.1

package/README.md

@@ -1,11 +1,11 @@
 # @lobomfz/db
 
-SQLite database with Arktype schemas and typed Kysely client.
+SQLite database with Arktype schemas and typed Kysely client for Bun.
 
 ## Install
 
 ```bash
-bun add @lobomfz/db
+bun add @lobomfz/db arktype kysely
 ```
 
 ## Usage
@@ -14,88 +14,67 @@ bun add @lobomfz/db
 import { Database, generated, type } from "@lobomfz/db";
 
 const db = new Database({
-	path: "data.db",
-	tables: {
-		users: type({
-			id: generated("autoincrement"),
-			name: "string",
-			email: type("string").configure({ unique: true }),
-			"bio?": "string",
-			created_at: generated("now"),
-		}),
-		posts: type({
-			id: generated("autoincrement"),
-			user_id: type("number.integer").configure({ references: "users.id", onDelete: "cascade" }),
-			title: "string",
-			tags: "string[]",
-			status: type("string").default("draft"),
-		}),
-	},
-	indexes: {
-		posts: [{ columns: ["user_id", "status"] }, { columns: ["title"], unique: true }],
-	},
+  path: "data.db",
+  schema: {
+    tables: {
+      users: type({
+        id: generated("autoincrement"),
+        name: "string",
+        email: type("string").configure({ unique: true }),
+        "bio?": "string",                    // optional → nullable in SQLite
+        active: type("boolean").default(true),
+        created_at: generated("now"),          // defaults to current time
+      }),
+      posts: type({
+        id: generated("autoincrement"),
+        user_id: type("number.integer").configure({ references: "users.id", onDelete: "cascade" }),
+        title: "string",
+        published_at: "Date",                   // native Date support
+        tags: "string[]",                      // JSON columns just work
+        metadata: type({ source: "string", "priority?": "number" }), // validated on write by default
+        status: type.enumerated("draft", "published").default("draft"),
+      }),
+    },
+    indexes: {
+      posts: [{ columns: ["user_id", "status"] }, { columns: ["title"], unique: true }],
+    },
+  },
+  pragmas: {
+    journal_mode: "wal",
+    synchronous: "normal",
+  },
 });
 
-// Fully typed Kysely client - fields with defaults are optional on insert
+// Fully typed Kysely client — generated/default fields are optional on insert
 await db.kysely.insertInto("users").values({ name: "John", email: "john@example.com" }).execute();
 
 const users = await db.kysely.selectFrom("users").selectAll().execute();
+// users[0].active     → true
+// users[0].created_at → Date
 ```
 
-## Features
-
-- Tables auto-created from Arktype schemas
-- Full TypeScript inference (insert vs select types)
-- JSON columns with validation
-- Foreign keys, unique constraints, defaults
-- Composite indexes
-
-## Generated Fields
-
-Use `generated()` for SQL-generated values:
-
-```typescript
-generated("autoincrement"); // INTEGER PRIMARY KEY AUTOINCREMENT
-generated("now"); // DEFAULT (unixepoch()) - Unix timestamp
-```
-
-## Default Values
+Booleans, dates, objects, arrays — everything round-trips as the type you declared. The schema is the source of truth for table creation, TypeScript types, and runtime coercion.
 
-Use Arktype's `.default()` for JS defaults (also creates SQL DEFAULT):
+## API
 
 ```typescript
-type("string").default("pending");
-type("number").default(0);
+generated("autoincrement");                                               // auto-incrementing primary key
+generated("now");                                                         // defaults to current timestamp, returned as Date
+type("string").default("pending");                                        // SQL DEFAULT
+type("string").configure({ unique: true });                               // UNIQUE
+type("number.integer").configure({ references: "users.id", onDelete: "cascade" }); // FK
 ```
 
-## Column Configuration
+JSON columns are validated against the schema on write by default. To also validate on read, or to disable write validation:
 
 ```typescript
-type("string").configure({ unique: true });
-type("number.integer").configure({ references: "users.id", onDelete: "cascade" });
-```
-
-`onDelete` options: `"cascade"`, `"set null"`, `"restrict"`
-
-## Composite Indexes
-
-```typescript
-const db = new Database({
-  tables: { ... },
-  indexes: {
-    posts: [
-      { columns: ["user_id", "category_id"], unique: true },
-      { columns: ["created_at"] },
-    ],
-  },
+new Database({
+  // ...
+  validation: { onRead: true },  // default: { onRead: false, onWrite: true }
 });
 ```
 
-## Errors
-
-```typescript
-import { JsonParseError, JsonValidationError } from "@lobomfz/db";
-```
+> **Note:** Migrations are not supported yet. Tables are created with `CREATE TABLE IF NOT EXISTS`.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lobomfz/db",
-	"version": "0.2.0",
+	"version": "0.2.1",
 	"description": "Bun SQLite database with Arktype schemas and typed Kysely client",
 	"keywords": [
 		"arktype",

package/src/database.ts

@@ -3,6 +3,7 @@ import { Kysely } from "kysely";
 import { BunSqliteDialect } from "./dialect/dialect";
 import type { Type } from "arktype";
 import type { GeneratedPreset } from "./generated";
+import type { DbFieldMeta } from "./env";
 import { DeserializePlugin, type ColumnCoercion, type ColumnsMap } from "./plugin";
 import type {
 	DatabaseOptions,
@@ -26,7 +27,7 @@ type StructureProp = {
 	value: Type & {
 		branches: ArkBranch[];
 		proto?: unknown;
-		meta: Record<string, unknown>;
+		meta: DbFieldMeta & { _generated?: GeneratedPreset };
 	};
 	inner: { default?: unknown };
 };
@@ -41,7 +42,7 @@ type Prop = {
 	isDate?: boolean;
 	isJson?: boolean;
 	jsonSchema?: Type;
-	meta?: Record<string, unknown>;
+	meta?: DbFieldMeta;
 	generated?: GeneratedPreset;
 	defaultValue?: unknown;
 };
@@ -71,9 +72,14 @@ export class Database<T extends SchemaRecord> {
 
 		this.createTables();
 
+		const validation = {
+			onRead: options.validation?.onRead ?? false,
+			onWrite: options.validation?.onWrite ?? true,
+		};
+
 		this.kysely = new Kysely<TablesFromSchemas<T>>({
 			dialect: new BunSqliteDialect({ database: this.sqlite }),
-			plugins: [new DeserializePlugin(this.columns)],
+			plugins: [new DeserializePlugin(this.columns, validation)],
 		});
 	}
 
@@ -95,10 +101,10 @@ export class Database<T extends SchemaRecord> {
 		}
 	}
 
-	private normalizeProp(structureProp: StructureProp, parentSchema: Type): Prop {
+	private normalizeProp(structureProp: StructureProp, parentSchema: Type) {
 		const { key, value: v, inner } = structureProp;
-		const kind = structureProp.required ? "required" : "optional";
-		const generated = v.meta._generated as GeneratedPreset | undefined;
+		const kind: Prop["kind"] = structureProp.required ? "required" : "optional";
+		const generated = v.meta._generated;
 		const defaultValue = inner.default;
 
 		const nonNull = v.branches.filter((b) => b.unit !== null);
@@ -155,7 +161,7 @@ export class Database<T extends SchemaRecord> {
 		return "TEXT";
 	}
 
-	private columnConstraint(prop: Prop): string | null {
+	private columnConstraint(prop: Prop) {
 		if (prop.generated === "autoincrement") {
 			return "PRIMARY KEY AUTOINCREMENT";
 		}
@@ -171,7 +177,7 @@ export class Database<T extends SchemaRecord> {
 		return null;
 	}
 
-	private defaultClause(prop: Prop): string | null {
+	private defaultClause(prop: Prop) {
 		if (prop.generated === "now") {
 			return "DEFAULT (unixepoch())";
 		}
@@ -192,7 +198,7 @@ export class Database<T extends SchemaRecord> {
 			return `DEFAULT ${prop.defaultValue}`;
 		}
 
-		return `DEFAULT '${String(prop.defaultValue)}'`;
+		throw new Error(`Unsupported default value type: ${typeof prop.defaultValue}`);
 	}
 
 	private columnDef(prop: Prop) {
@@ -208,7 +214,7 @@ export class Database<T extends SchemaRecord> {
 	}
 
 	private foreignKey(prop: Prop) {
-		const ref = prop.meta?.references as string | undefined;
+		const ref = prop.meta?.references;
 
 		if (!ref) {
 			return null;
@@ -218,7 +224,7 @@ export class Database<T extends SchemaRecord> {
 
 		let fk = `FOREIGN KEY ("${prop.key}") REFERENCES "${table}"("${column}")`;
 
-		const onDelete = prop.meta?.onDelete as string | undefined;
+		const onDelete = prop.meta?.onDelete;
 
 		if (onDelete) {
 			fk += ` ON DELETE ${onDelete.toUpperCase()}`;

package/src/dialect/connection.ts

@@ -1,4 +1,4 @@
-import { Database } from "bun:sqlite";
+import type { Database } from "bun:sqlite";
 import type { CompiledQuery, DatabaseConnection, QueryResult } from "kysely";
 import { serializeParam } from "./serialize";
 
@@ -9,30 +9,30 @@ export class BunSqliteConnection implements DatabaseConnection {
 		this.#db = db;
 	}
 
-	executeQuery<O>(compiledQuery: CompiledQuery): Promise<QueryResult<O>> {
-		const { sql, parameters } = compiledQuery;
-		const serializedParams = parameters.map(serializeParam);
-		const stmt = this.#db.query(sql);
+	async executeQuery<O>(compiled: CompiledQuery): Promise<QueryResult<O>> {
+		const serializedParams = compiled.parameters.map(serializeParam);
+
+		const stmt = this.#db.query(compiled.sql);
 
 		if (stmt.columnNames.length > 0) {
-			return Promise.resolve({
+			return {
 				rows: stmt.all(serializedParams as any) as O[],
-			});
+			};
 		}
 
 		const results = stmt.run(serializedParams as any);
 
-		return Promise.resolve({
+		return {
 			insertId: BigInt(results.lastInsertRowid),
 			numAffectedRows: BigInt(results.changes),
 			rows: [],
-		});
+		};
 	}
 
 	async *streamQuery<R>(compiledQuery: CompiledQuery): AsyncIterableIterator<QueryResult<R>> {
-		const { sql, parameters } = compiledQuery;
-		const serializedParams = parameters.map(serializeParam);
-		const stmt = this.#db.prepare(sql);
+		const serializedParams = compiledQuery.parameters.map(serializeParam);
+
+		const stmt = this.#db.prepare(compiledQuery.sql);
 
 		for await (const row of stmt.iterate(serializedParams as any)) {
 			yield { rows: [row as R] };

package/src/dialect/driver.ts

@@ -1,4 +1,4 @@
-import { Database } from "bun:sqlite";
+import type { Database } from "bun:sqlite";
 import { CompiledQuery, type DatabaseConnection, type Driver } from "kysely";
 import type { BunSqliteDialectConfig } from "./config";
 import { BunSqliteConnection } from "./connection";
@@ -38,12 +38,10 @@ export class BunSqliteDriver implements Driver {
 		await connection.executeQuery(CompiledQuery.raw("rollback"));
 	}
 
-	// oxlint-disable-next-line require-await
 	async releaseConnection(): Promise<void> {
 		this.#connectionMutex.unlock();
 	}
 
-	// oxlint-disable-next-line require-await
 	async destroy(): Promise<void> {
 		this.#db?.close();
 	}

package/src/index.ts

@@ -14,5 +14,6 @@ export type {
 	IndexesConfig,
 	DatabasePragmas,
 	DatabaseSchema,
+	JsonValidation,
 	SqliteMasterRow,
 } from "./types";

package/src/plugin.ts

@@ -1,40 +1,71 @@
-import { type KyselyPlugin, type RootOperationNode, type UnknownRow } from "kysely";
+import {
+	type KyselyPlugin,
+	type RootOperationNode,
+	type UnknownRow,
+	type QueryId,
+	TableNode,
+	AliasNode,
+	ValuesNode,
+	ValueNode,
+	ColumnNode,
+} from "kysely";
 import { type } from "arktype";
 import type { Type } from "arktype";
 import { JsonParseError } from "./errors";
 import { JsonValidationError } from "./validation-error";
+import type { JsonValidation } from "./types";
 
 export type ColumnCoercion = "boolean" | "date" | { type: "json"; schema: Type };
 export type ColumnsMap = Map<string, Map<string, ColumnCoercion>>;
 
 export class DeserializePlugin implements KyselyPlugin {
-	private queryNodes = new Map<unknown, RootOperationNode>();
+	private queryNodes = new WeakMap<QueryId, RootOperationNode>();
 
-	constructor(private columns: ColumnsMap) {}
+	constructor(
+		private columns: ColumnsMap,
+		private validation: Required<JsonValidation>,
+	) {}
 
 	transformQuery: KyselyPlugin["transformQuery"] = (args) => {
 		this.queryNodes.set(args.queryId, args.node);
 
+		if (this.validation.onWrite) {
+			this.validateWriteNode(args.node);
+		}
+
 		return args.node;
 	};
 
-	private getTableFromNode(node: RootOperationNode): string | null {
+	private getTableFromNode(node: RootOperationNode) {
 		switch (node.kind) {
 			case "InsertQueryNode":
-				return (node as any).into?.table?.identifier?.name ?? null;
+				return node.into?.table.identifier.name ?? null;
 
-			case "UpdateQueryNode":
-				return (node as any).table?.table?.identifier?.name ?? null;
+			case "UpdateQueryNode": {
+				if (node.table && TableNode.is(node.table)) {
+					return node.table.table.identifier.name;
+				}
+
+				return null;
+			}
 
 			case "SelectQueryNode":
 			case "DeleteQueryNode": {
-				const fromNode = (node as any).from?.froms?.[0];
+				const fromNode = node.from?.froms[0];
+
+				if (!fromNode) {
+					return null;
+				}
+
+				if (AliasNode.is(fromNode) && TableNode.is(fromNode.node)) {
+					return fromNode.node.table.identifier.name;
+				}
 
-				if (fromNode?.kind === "AliasNode") {
-					return fromNode.node?.table?.identifier?.name ?? null;
+				if (TableNode.is(fromNode)) {
+					return fromNode.table.identifier.name;
 				}
 
-				return fromNode?.table?.identifier?.name ?? null;
+				return null;
 			}
 
 			default:
@@ -42,6 +73,82 @@ export class DeserializePlugin implements KyselyPlugin {
 		}
 	}
 
+	private validateJsonValue(table: string, col: string, value: unknown, schema: Type) {
+		if (value === null || value === undefined) {
+			return;
+		}
+
+		const result = schema(value);
+
+		if (result instanceof type.errors) {
+			throw new JsonValidationError(table, col, result.summary);
+		}
+	}
+
+	private validateWriteNode(node: RootOperationNode) {
+		if (node.kind !== "InsertQueryNode" && node.kind !== "UpdateQueryNode") {
+			return;
+		}
+
+		const table = this.getTableFromNode(node);
+
+		if (!table) {
+			return;
+		}
+
+		const cols = this.columns.get(table);
+
+		if (!cols) {
+			return;
+		}
+
+		for (const [col, value] of this.writeValues(node)) {
+			const coercion = cols.get(col);
+
+			if (!coercion || typeof coercion === "string") {
+				continue;
+			}
+
+			this.validateJsonValue(table, col, value, coercion.schema);
+		}
+	}
+
+	private *writeValues(node: RootOperationNode) {
+		if (node.kind === "InsertQueryNode") {
+			const columns = node.columns?.map((c) => c.column.name);
+
+			if (!columns || !node.values || !ValuesNode.is(node.values)) {
+				return;
+			}
+
+			for (const valueList of node.values.values) {
+				for (let i = 0; i < columns.length; i++) {
+					const col = columns[i]!;
+
+					if (valueList.kind === "PrimitiveValueListNode") {
+						yield [col, valueList.values[i]] as [string, unknown];
+						continue;
+					}
+
+					const raw = valueList.values[i];
+					yield [col, raw && ValueNode.is(raw) ? raw.value : raw] as [string, unknown];
+				}
+			}
+
+			return;
+		}
+
+		if (node.kind !== "UpdateQueryNode" || !node.updates) {
+			return;
+		}
+
+		for (const update of node.updates) {
+			if (ColumnNode.is(update.column) && ValueNode.is(update.value)) {
+				yield [update.column.column.name, update.value.value] as [string, unknown];
+			}
+		}
+	}
+
 	private coerceRow(table: string, row: UnknownRow, cols: Map<string, ColumnCoercion>) {
 		for (const [col, coercion] of cols) {
 			if (!(col in row)) {
@@ -78,17 +185,14 @@ export class DeserializePlugin implements KyselyPlugin {
 				throw new JsonParseError(table, col, value, e);
 			}
 
-			const validated = coercion.schema(parsed);
-
-			if (validated instanceof type.errors) {
-				throw new JsonValidationError(table, col, validated.summary);
+			if (this.validation.onRead) {
+				this.validateJsonValue(table, col, parsed, coercion.schema);
 			}
 
-			row[col] = validated;
+			row[col] = parsed;
 		}
 	}
 
-	// oxlint-disable-next-line require-await
 	transformResult: KyselyPlugin["transformResult"] = async (args) => {
 		const node = this.queryNodes.get(args.queryId);
 

package/src/types.ts

@@ -58,8 +58,14 @@ export type DatabaseSchema<T extends SchemaRecord> = {
 	indexes?: IndexesConfig<T>;
 };
 
+export type JsonValidation = {
+	onRead?: boolean;
+	onWrite?: boolean;
+};
+
 export type DatabaseOptions<T extends SchemaRecord> = {
 	path: string;
 	schema: DatabaseSchema<T>;
 	pragmas?: DatabasePragmas;
+	validation?: JsonValidation;
 };