@lobomfz/db 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 lobomfz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# @lobomfz/db
+
+SQLite database with Arktype schemas and typed Kysely client.
+
+## Install
+
+```bash
+bun add @lobomfz/db arktype kysely
+```
+
+## Usage
+
+```typescript
+import { type } from "arktype";
+import { Database, autoIncrement } from "@lobomfz/db";
+
+const db = new Database({
+  path: "data.db",
+  tables: {
+    users: type({
+      id: autoIncrement(),
+      name: "string",
+      email: type("string").configure({ unique: true }),
+      "bio?": "string",
+    }),
+    posts: type({
+      id: autoIncrement(),
+      user_id: type("number.integer").configure({ references: "users.id", onDelete: "cascade" }),
+      title: "string",
+      tags: "string[]",
+    }),
+  },
+});
+
+// Fully typed Kysely client
+await db.kysely.insertInto("users").values({ name: "John", email: "john@example.com" }).execute();
+
+const users = await db.kysely.selectFrom("users").selectAll().execute();
+```
+
+## Features
+
+- Tables auto-created from Arktype schemas
+- Full TypeScript inference
+- JSON columns with validation
+- Foreign keys, unique constraints, defaults
+- `autoIncrement()` for primary keys
+
+## Column Configuration
+
+```typescript
+type("string").configure({ unique: true })
+type("string").configure({ default: "pending" })
+type("number.integer").configure({ default: "now" }) // Unix timestamp
+type("number.integer").configure({ references: "users.id", onDelete: "cascade" })
+```
+
+`onDelete` options: `"cascade"`, `"set null"`, `"restrict"`
+
+## Errors
+
+```typescript
+import { JsonParseError, JsonValidationError } from "@lobomfz/db";
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "@lobomfz/db",
+	"version": "0.1.0",
+	"description": "SQLite database with Arktype schemas and typed Kysely client",
+	"license": "MIT",
+	"author": "lobomfz",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/lobomfz/db.git"
+	},
+	"keywords": [
+		"sqlite",
+		"database",
+		"arktype",
+		"kysely",
+		"typescript",
+		"bun",
+		"schema",
+		"validation"
+	],
+	"files": [
+		"src"
+	],
+	"type": "module",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"import": "./src/index.ts"
+		}
+	},
+	"scripts": {
+		"check": "tsc"
+	},
+	"dependencies": {
+		"@lobomfz/kysely-bun-sqlite": "^0.4.1"
+	},
+	"devDependencies": {
+		"@types/bun": "latest",
+		"arktype": "^2.1.29",
+		"oxfmt": "^0.26.0",
+		"oxlint": "^1.41.0"
+	},
+	"peerDependencies": {
+		"arktype": "^2.1.0",
+		"kysely": "^0.27.0",
+		"typescript": "^5"
+	}
+}

package/src/autoincrement.ts

@@ -0,0 +1,14 @@
+import { type, Type } from "arktype";
+
+declare const AutoIncrementBrand: unique symbol;
+
+export type AutoIncrementNumber = number & { [AutoIncrementBrand]: true };
+
+export type AutoIncrementType = Type<AutoIncrementNumber>;
+
+export const autoIncrement = (): AutoIncrementType => {
+	return type("number.integer").configure({
+		primaryKey: true,
+		_autoincrement: true,
+	} as any) as unknown as AutoIncrementType;
+};

package/src/database.ts

@@ -0,0 +1,235 @@
+import { Database as BunDatabase } from "bun:sqlite";
+import { Kysely } from "kysely";
+import { BunSqliteDialect } from "@lobomfz/kysely-bun-sqlite";
+import type { Type } from "arktype";
+import type { DbFieldMeta } from "./env";
+import { JsonPlugin, type JsonColumnsMap } from "./plugin";
+import type { DatabaseOptions, SchemaRecord, TablesFromSchemas } from "./types";
+
+type PropValue =
+	| string
+	| { unit: unknown }[]
+	| {
+			domain?: string | { domain: string };
+			divisor?: { rule: number };
+			meta?: DbFieldMeta;
+			proto?: string;
+			sequence?: unknown;
+			required?: RawProp[];
+			optional?: RawProp[];
+	  };
+
+type RawProp = { key: string; value: PropValue };
+type InnerJson = { required?: RawProp[]; optional?: RawProp[] };
+
+type Prop = {
+	key: string;
+	kind: "required" | "optional";
+	domain?: string;
+	isBoolean?: boolean;
+	isInteger?: boolean;
+	isJson?: boolean;
+	jsonSchema?: Type;
+	meta?: DbFieldMeta;
+};
+
+const typeMap: Record<string, string> = {
+	string: "TEXT",
+	number: "REAL",
+};
+
+export class Database<T extends SchemaRecord> {
+	private sqlite: BunDatabase;
+
+	private jsonColumns: JsonColumnsMap = new Map();
+
+	readonly infer: TablesFromSchemas<T> = undefined as any;
+
+	readonly kysely: Kysely<TablesFromSchemas<T>>;
+
+	constructor(private options: DatabaseOptions<T>) {
+		this.sqlite = new BunDatabase(options.path);
+
+		this.sqlite.run("PRAGMA foreign_keys = ON");
+
+		this.createTables();
+
+		this.kysely = new Kysely<TablesFromSchemas<T>>({
+			dialect: new BunSqliteDialect({ database: this.sqlite }),
+			plugins: [new JsonPlugin(this.jsonColumns)],
+		});
+	}
+
+	private isJsonValue(value: PropValue): boolean {
+		if (typeof value === "string" || Array.isArray(value)) return false;
+
+		if (value.proto === "Array") return true;
+		if (value.domain === "object" && (value.required || value.optional)) return true;
+
+		return false;
+	}
+
+	private normalizeProp(raw: RawProp, kind: "required" | "optional", parentSchema: Type): Prop {
+		const { key, value } = raw;
+
+		if (typeof value === "string") {
+			return { key, kind, domain: value };
+		}
+
+		if (Array.isArray(value)) {
+			let hasTrue = false;
+			let hasFalse = false;
+
+			for (const u of value) {
+				if (u.unit === true) hasTrue = true;
+				if (u.unit === false) hasFalse = true;
+			}
+
+			const isBool = value.length === 2 && hasTrue && hasFalse;
+
+			return { key, kind, isBoolean: isBool };
+		}
+
+		if (this.isJsonValue(value)) {
+			return {
+				key,
+				kind,
+				isJson: true,
+				jsonSchema: (parentSchema as any).get(key) as Type,
+				meta: value.meta,
+			};
+		}
+
+		const domain = typeof value.domain === "string" ? value.domain : value.domain?.domain;
+
+		return {
+			key,
+			kind,
+			domain,
+			isInteger: value.divisor?.rule === 1,
+			meta: value.meta,
+		};
+	}
+
+	private sqlType(prop: Prop) {
+		if (prop.isJson) return "TEXT";
+		if (prop.isBoolean || prop.isInteger) return "INTEGER";
+		if (prop.domain && typeMap[prop.domain]) return typeMap[prop.domain];
+		return "TEXT";
+	}
+
+	private columnDef(prop: Prop) {
+		const parts = [`"${prop.key}"`, this.sqlType(prop)];
+		const meta = prop.meta;
+
+		if (meta?.primaryKey) {
+			parts.push("PRIMARY KEY");
+			if ((meta as any)._autoincrement) parts.push("AUTOINCREMENT");
+		} else if (prop.kind === "required") {
+			parts.push("NOT NULL");
+		}
+
+		if (meta?.unique) parts.push("UNIQUE");
+
+		if (meta?.default !== undefined) {
+			let val: string | number | boolean;
+
+			if (meta.default === "now") {
+				val = "(unixepoch())";
+			} else if (typeof meta.default === "string") {
+				val = `'${meta.default}'`;
+			} else {
+				val = meta.default;
+			}
+
+			parts.push(`DEFAULT ${val}`);
+		}
+
+		return parts.join(" ");
+	}
+
+	private foreignKey(prop: Prop) {
+		const ref = prop.meta?.references;
+		if (!ref) return null;
+
+		const [table, column] = ref.split(".");
+		let fk = `FOREIGN KEY ("${prop.key}") REFERENCES "${table}"("${column}")`;
+
+		switch (prop.meta?.onDelete) {
+			case "cascade":
+				fk += " ON DELETE CASCADE";
+				break;
+			case "set null":
+				fk += " ON DELETE SET NULL";
+				break;
+			case "restrict":
+				fk += " ON DELETE RESTRICT";
+				break;
+		}
+
+		return fk;
+	}
+
+	private parseSchemaProps(schema: Type) {
+		const { required = [], optional = [] } = (schema as any).innerJson as InnerJson;
+		const props: Prop[] = [];
+
+		for (const r of required) {
+			props.push(this.normalizeProp(r, "required", schema));
+		}
+
+		for (const r of optional) {
+			props.push(this.normalizeProp(r, "optional", schema));
+		}
+
+		return props;
+	}
+
+	private registerJsonColumns(tableName: string, props: Prop[]) {
+		const tableJsonCols = new Map<string, { schema: Type }>();
+
+		for (const prop of props) {
+			if (!prop.isJson || !prop.jsonSchema) continue;
+
+			tableJsonCols.set(prop.key, { schema: prop.jsonSchema });
+		}
+
+		if (tableJsonCols.size === 0) return;
+
+		this.jsonColumns.set(tableName, tableJsonCols);
+	}
+
+	private generateCreateTableSQL(tableName: string, props: Prop[]) {
+		const columns: string[] = [];
+		const fks: string[] = [];
+
+		for (const prop of props) {
+			columns.push(this.columnDef(prop));
+
+			const fk = this.foreignKey(prop);
+			if (fk) fks.push(fk);
+		}
+
+		return `CREATE TABLE IF NOT EXISTS "${tableName}" (${columns.concat(fks).join(", ")})`;
+	}
+
+	private createTables() {
+		for (const [name, schema] of Object.entries(this.options.tables)) {
+			const props = this.parseSchemaProps(schema);
+
+			this.registerJsonColumns(name, props);
+			this.sqlite.run(this.generateCreateTableSQL(name, props));
+		}
+	}
+
+	reset(table?: keyof T & string) {
+		const tables = table ? [table] : Object.keys(this.options.tables);
+		for (const t of tables) {
+			this.sqlite.run(`DELETE FROM "${t}"`);
+		}
+	}
+
+	close() {
+		this.sqlite.close();
+	}
+}

package/src/env.ts

@@ -0,0 +1,13 @@
+export type DbFieldMeta = {
+	primaryKey?: boolean;
+	unique?: boolean;
+	references?: `${string}.${string}`;
+	onDelete?: "cascade" | "set null" | "restrict";
+	default?: "now" | number | string | boolean;
+};
+
+declare global {
+	interface ArkEnv {
+		meta(): DbFieldMeta;
+	}
+}

package/src/errors.ts

@@ -0,0 +1,14 @@
+export class JsonParseError extends Error {
+	readonly table: string;
+	readonly column: string;
+	readonly value: string;
+
+	constructor(table: string, column: string, value: string, cause: unknown) {
+		super(`Failed to parse JSON in ${table}.${column}`);
+		this.name = "JsonParseError";
+		this.table = table;
+		this.column = column;
+		this.value = value;
+		this.cause = cause;
+	}
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { Database } from "./database.ts";
+export { autoIncrement } from "./autoincrement.ts";
+export { JsonParseError } from "./errors.ts";
+export { JsonValidationError } from "./validation-error.ts";
+export type { DbFieldMeta } from "./env.ts";
+export type { DatabaseOptions, SchemaRecord, TablesFromSchemas, InferTableType } from "./types.ts";

package/src/plugin.ts

@@ -0,0 +1,82 @@
+import {
+	type KyselyPlugin,
+	type PluginTransformQueryArgs,
+	type PluginTransformResultArgs,
+	type QueryResult,
+	type RootOperationNode,
+	type UnknownRow,
+} from "kysely";
+import { type } from "arktype";
+import type { Type } from "arktype";
+import { JsonSerializer } from "./serializer";
+import { JsonParseError } from "./errors";
+import { JsonValidationError } from "./validation-error";
+
+export type JsonColumnInfo = { schema: Type };
+export type JsonColumnsMap = Map<string, Map<string, JsonColumnInfo>>;
+
+export class JsonPlugin implements KyselyPlugin {
+	private serializer = new JsonSerializer();
+	private queryNodes = new Map<unknown, RootOperationNode>();
+
+	constructor(private jsonColumns: JsonColumnsMap) {}
+
+	transformQuery(args: PluginTransformQueryArgs): RootOperationNode {
+		this.queryNodes.set(args.queryId, args.node);
+		return this.serializer.transformNode(args.node);
+	}
+
+	private getTableFromNode(node: RootOperationNode): string | null {
+		switch (node.kind) {
+			case "InsertQueryNode":
+			case "UpdateQueryNode":
+				return (node as any).table?.table?.identifier?.name ?? null;
+
+			case "SelectQueryNode":
+			case "DeleteQueryNode":
+				return (node as any).from?.froms?.[0]?.table?.identifier?.name ?? null;
+
+			default:
+				return null;
+		}
+	}
+
+	// oxlint-disable-next-line require-await
+	async transformResult(args: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>> {
+		const node = this.queryNodes.get(args.queryId);
+		this.queryNodes.delete(args.queryId);
+
+		if (!node) return args.result;
+
+		const table = this.getTableFromNode(node);
+
+		if (!table) return args.result;
+
+		const columns = this.jsonColumns.get(table);
+
+		if (!columns) return args.result;
+
+		for (const row of args.result.rows) {
+			for (const [col, info] of columns.entries()) {
+				if (!(col in row) || typeof row[col] !== "string") continue;
+
+				const value = row[col] as string;
+
+				let parsed: unknown;
+				try {
+					parsed = JSON.parse(value);
+				} catch (e) {
+					throw new JsonParseError(table, col, value, e);
+				}
+
+				const validated = info.schema(parsed);
+				if (validated instanceof type.errors) {
+					throw new JsonValidationError(table, col, validated.summary);
+				}
+				row[col] = validated;
+			}
+		}
+
+		return { ...args.result };
+	}
+}

package/src/serializer.ts

@@ -0,0 +1,19 @@
+import { OperationNodeTransformer, type PrimitiveValueListNode } from "kysely";
+
+export class JsonSerializer extends OperationNodeTransformer {
+	protected override transformPrimitiveValueList(
+		node: PrimitiveValueListNode,
+	): PrimitiveValueListNode {
+		const values: unknown[] = [];
+
+		for (const v of node.values) {
+			if (typeof v === "object" && v !== null && !ArrayBuffer.isView(v)) {
+				values.push(JSON.stringify(v));
+			} else {
+				values.push(v);
+			}
+		}
+
+		return super.transformPrimitiveValueList({ ...node, values });
+	}
+}

package/src/types.ts

@@ -0,0 +1,34 @@
+import type { Generated } from "kysely";
+import type { Type } from "arktype";
+import type { AutoIncrementNumber } from "./autoincrement";
+
+type NullableIf<T, Condition> = Condition extends true ? T | null : T;
+
+type IsOptional<T, K extends keyof T> = undefined extends T[K] ? true : false;
+
+type TransformColumn<T> = T extends AutoIncrementNumber
+	? Generated<number>
+	: T extends boolean
+		? number
+		: T extends (infer U)[]
+			? U[]
+			: T extends object
+				? T
+				: T;
+
+type TransformTable<T> = {
+	[K in keyof T]: NullableIf<TransformColumn<NonNullable<T[K]>>, IsOptional<T, K>>;
+};
+
+export type SchemaRecord = Record<string, Type>;
+
+export type InferTableType<T> = T extends Type<infer Output> ? TransformTable<Output> : never;
+
+export type TablesFromSchemas<T extends SchemaRecord> = {
+	[K in keyof T]: InferTableType<T[K]>;
+};
+
+export type DatabaseOptions<T extends SchemaRecord> = {
+	path: string;
+	tables: T;
+};

package/src/validation-error.ts

@@ -0,0 +1,13 @@
+export class JsonValidationError extends Error {
+	readonly table: string;
+	readonly column: string;
+	readonly summary: string;
+
+	constructor(table: string, column: string, summary: string) {
+		super(`JSON validation failed for ${table}.${column}: ${summary}`);
+		this.name = "JsonValidationError";
+		this.table = table;
+		this.column = column;
+		this.summary = summary;
+	}
+}