From 9e922be19933bd8ae086810f40f751a66f179f29 Mon Sep 17 00:00:00 2001 From: Benjamin Toby Date: Sun, 8 Mar 2026 08:24:36 +0100 Subject: [PATCH] Updates --- CLAUDE.md | 106 -------------------------------------- README.md | 141 +++++++++++++++++++++++++++++---------------------- package.json | 4 +- 3 files changed, 81 insertions(+), 170 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 1ee6890..e69de29 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,106 +0,0 @@ - -Default to using Bun instead of Node.js. - -- Use `bun ` instead of `node ` or `ts-node ` -- Use `bun test` instead of `jest` or `vitest` -- Use `bun build ` instead of `webpack` or `esbuild` -- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install` -- Use `bun run - - -``` - -With the following `frontend.tsx`: - -```tsx#frontend.tsx -import React from "react"; - -// import .css files directly and it works -import './index.css'; - -import { createRoot } from "react-dom/client"; - -const root = createRoot(document.body); - -export default function Frontend() { - return

Hello, world!

; -} - -root.render(); -``` - -Then, run index.ts - -```sh -bun --hot ./index.ts -``` - -For more information, read the Bun API docs in `node_modules/bun-types/docs/**.md`. diff --git a/README.md b/README.md index f932c8b..302bd01 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # Node SQLite -@moduletrace/bun-sqlite +@moduletrace/nsqlite -A schema-driven SQLite manager for [Bun](https://bun.sh), featuring automatic schema synchronization, type-safe CRUD operations, vector embedding support (via `sqlite-vec`), and TypeScript type definition generation. +A schema-driven SQLite manager for Node.js, featuring automatic schema synchronization, type-safe CRUD operations, vector embedding support (via `sqlite-vec`), and TypeScript type definition generation. --- @@ -47,7 +47,7 @@ A schema-driven SQLite manager for [Bun](https://bun.sh), featuring automatic sc ## Prerequisites -`@moduletrace/bun-sqlite` is published to a private Gitea npm registry. You must configure your package manager to resolve the `@moduletrace` scope from that registry before installing. +`@moduletrace/nsqlite` is published to a private Gitea npm registry. You must configure your package manager to resolve the `@moduletrace` scope from that registry before installing. Add the following to your project's `.npmrc` file (create it at the root of your project if it doesn't exist): @@ -55,14 +55,12 @@ Add the following to your project's `.npmrc` file (create it at the root of your @moduletrace:registry=https://git.tben.me/api/packages/moduletrace/npm/ ``` -This works for both `bun` and `npm`. - --- ## Installation ```bash -bun add @moduletrace/bun-sqlite +npm install @moduletrace/nsqlite ``` --- @@ -74,7 +72,7 @@ bun add @moduletrace/bun-sqlite Create `bun-sqlite.config.ts` at your project root: ```ts -import type { BunSQLiteConfig } from "@moduletrace/bun-sqlite"; +import type { BunSQLiteConfig } from "@moduletrace/nsqlite"; const config: BunSQLiteConfig = { db_name: "my-app.db", @@ -92,7 +90,7 @@ export default config; Create `./db/schema.ts` (matching `db_schema_file_name` above): ```ts -import type { BUN_SQLITE_DatabaseSchemaType } from "@moduletrace/bun-sqlite"; +import type { BUN_SQLITE_DatabaseSchemaType } from "@moduletrace/nsqlite"; const schema: BUN_SQLITE_DatabaseSchemaType = { dbName: "my-app", @@ -114,7 +112,7 @@ export default schema; ### 3. Sync the schema to SQLite ```bash -bunx bun-sqlite schema +npx bun-sqlite schema ``` This creates the SQLite database file and creates/updates all tables to match your schema. @@ -122,27 +120,27 @@ This creates the SQLite database file and creates/updates all tables to match yo ### 4. Use the CRUD API ```ts -import BunSQLite from "@moduletrace/bun-sqlite"; +import NodeSQLite from "@moduletrace/nsqlite"; // Insert -await BunSQLite.insert({ +await NodeSQLite.insert({ table: "users", data: [{ first_name: "Alice", email: "alice@example.com" }], }); // Select -const result = await BunSQLite.select({ table: "users" }); +const result = await NodeSQLite.select({ table: "users" }); console.log(result.payload); // Alice's row // Update -await BunSQLite.update({ +await NodeSQLite.update({ table: "users", targetId: 1, data: { first_name: "Alicia" }, }); // Delete -await BunSQLite.delete({ table: "users", targetId: 1 }); +await NodeSQLite.delete({ table: "users", targetId: 1 }); ``` --- @@ -248,7 +246,7 @@ The package provides a `bun-sqlite` CLI binary. ### `schema` — Sync database to schema ```bash -bunx bun-sqlite schema [options] +npx bun-sqlite schema [options] ``` | Option | Description | @@ -260,19 +258,19 @@ bunx bun-sqlite schema [options] ```bash # Sync schema only -bunx bun-sqlite schema +npx bun-sqlite schema # Sync schema and regenerate types -bunx bun-sqlite schema --typedef +npx bun-sqlite schema --typedef # Sync schema, recreate vector tables, and regenerate types -bunx bun-sqlite schema --vector --typedef +npx bun-sqlite schema --vector --typedef ``` ### `typedef` — Generate TypeScript types only ```bash -bunx bun-sqlite typedef +npx bun-sqlite typedef ``` Reads the schema and writes TypeScript type definitions to the path configured in `typedef_file_path`. @@ -282,7 +280,7 @@ Reads the schema and writes TypeScript type definitions to the path configured i ### `backup` — Back up the database ```bash -bunx bun-sqlite backup +npx bun-sqlite backup ``` Copies the current database file into `db_backup_dir` with a timestamped filename. After copying, the oldest backups are automatically pruned so the number of stored backups never exceeds `max_backups` (default: 10). @@ -290,7 +288,7 @@ Copies the current database file into `db_backup_dir` with a timestamped filenam **Example:** ```bash -bunx bun-sqlite backup +npx bun-sqlite backup # Backing up database ... # DB Backup Success! ``` @@ -300,7 +298,7 @@ bunx bun-sqlite backup ### `restore` — Restore the database from a backup ```bash -bunx bun-sqlite restore +npx bun-sqlite restore ``` Presents an interactive list of available backups sorted by date (newest first). Select a backup to overwrite the current database file with it. @@ -308,7 +306,7 @@ Presents an interactive list of available backups sorted by date (newest first). **Example:** ```bash -bunx bun-sqlite restore +npx bun-sqlite restore # Restoring up database ... # ? Select a backup: (Use arrow keys) # ❯ Backup #1: Mon Mar 02 2026 14:30:00 @@ -325,7 +323,7 @@ bunx bun-sqlite restore Import the default export: ```ts -import BunSQLite from "@moduletrace/bun-sqlite"; +import NodeSQLite from "@moduletrace/nsqlite"; ``` All methods return an `APIResponseObject`: @@ -351,7 +349,7 @@ All methods return an `APIResponseObject`: ### Select ```ts -BunSQLite.select({ table, query?, count?, targetId? }) +NodeSQLite.select({ table, query?, count?, targetId? }) ``` | Parameter | Type | Description | @@ -365,13 +363,13 @@ BunSQLite.select({ table, query?, count?, targetId? }) ```ts // Get all users -const res = await BunSQLite.select({ table: "users" }); +const res = await NodeSQLite.select({ table: "users" }); // Get by ID -const res = await BunSQLite.select({ table: "users", targetId: 42 }); +const res = await NodeSQLite.select({ table: "users", targetId: 42 }); // Filter with LIKE -const res = await BunSQLite.select({ +const res = await NodeSQLite.select({ table: "users", query: { query: { @@ -381,11 +379,11 @@ const res = await BunSQLite.select({ }); // Count rows -const res = await BunSQLite.select({ table: "users", count: true }); +const res = await NodeSQLite.select({ table: "users", count: true }); console.log(res.count); // Pagination -const res = await BunSQLite.select({ +const res = await NodeSQLite.select({ table: "users", query: { limit: 10, page: 2 }, }); @@ -396,7 +394,7 @@ const res = await BunSQLite.select({ ### Insert ```ts -BunSQLite.insert({ table, data }); +NodeSQLite.insert({ table, data }); ``` | Parameter | Type | Description | @@ -409,7 +407,7 @@ BunSQLite.insert({ table, data }); **Example:** ```ts -const res = await BunSQLite.insert({ +const res = await NodeSQLite.insert({ table: "users", data: [ { first_name: "Alice", last_name: "Smith", email: "alice@example.com" }, @@ -425,7 +423,7 @@ console.log(res.postInsertReturn?.insertId); // last inserted row ID ### Update ```ts -BunSQLite.update({ table, data, query?, targetId? }) +NodeSQLite.update({ table, data, query?, targetId? }) ``` | Parameter | Type | Description | @@ -443,14 +441,14 @@ A WHERE clause is required. If no condition matches, `success` is `false`. ```ts // Update by ID -await BunSQLite.update({ +await NodeSQLite.update({ table: "users", targetId: 1, data: { first_name: "Alicia" }, }); // Update with custom query -await BunSQLite.update({ +await NodeSQLite.update({ table: "users", data: { last_name: "Doe" }, query: { @@ -466,7 +464,7 @@ await BunSQLite.update({ ### Delete ```ts -BunSQLite.delete({ table, query?, targetId? }) +NodeSQLite.delete({ table, query?, targetId? }) ``` | Parameter | Type | Description | @@ -481,10 +479,10 @@ A WHERE clause is required. If no condition is provided, `success` is `false`. ```ts // Delete by ID -await BunSQLite.delete({ table: "users", targetId: 1 }); +await NodeSQLite.delete({ table: "users", targetId: 1 }); // Delete with condition -await BunSQLite.delete({ +await NodeSQLite.delete({ table: "users", query: { query: { @@ -499,7 +497,7 @@ await BunSQLite.delete({ ### Raw SQL ```ts -BunSQLite.sql({ sql, values? }) +NodeSQLite.sql({ sql, values? }) ``` | Parameter | Type | Description | @@ -513,11 +511,11 @@ SELECT statements return rows; all other statements return `postInsertReturn`. ```ts // SELECT -const res = await BunSQLite.sql({ sql: "SELECT * FROM users" }); +const res = await NodeSQLite.sql({ sql: "SELECT * FROM users" }); console.log(res.payload); // INSERT with params -await BunSQLite.sql({ +await NodeSQLite.sql({ sql: "INSERT INTO users (first_name, email) VALUES (?, ?)", values: ["Charlie", "charlie@example.com"], }); @@ -566,7 +564,13 @@ Set `equality` on any query field to control the comparison: | `LIKE` | `LIKE '%value%'` | | `LIKE_RAW` | `LIKE 'value'` (no auto-wrapping) | | `LIKE_LOWER` | `LOWER(field) LIKE '%value%'` | +| `LIKE_LOWER_RAW` | `LOWER(field) LIKE 'value'` (no auto-wrapping) | | `NOT LIKE` | `NOT LIKE '%value%'` | +| `NOT LIKE_RAW` | `NOT LIKE 'value'` (no auto-wrapping) | +| `NOT_LIKE_LOWER` | `LOWER(field) NOT LIKE '%value%'` | +| `NOT_LIKE_LOWER_RAW` | `LOWER(field) NOT LIKE 'value'` (no auto-wrapping) | +| `REGEXP` | `REGEXP 'value'` | +| `FULLTEXT` | Full-text search match | | `GREATER THAN` | `>` | | `GREATER THAN OR EQUAL` | `>=` | | `LESS THAN` | `<` | @@ -574,15 +578,19 @@ Set `equality` on any query field to control the comparison: | `IN` | `IN (val1, val2, ...)` — pass array as value | | `NOT IN` | `NOT IN (...)` | | `BETWEEN` | `BETWEEN val1 AND val2` — pass `[val1, val2]` as value | +| `NOT BETWEEN` | `NOT BETWEEN val1 AND val2` | | `IS NULL` | `IS NULL` | | `IS NOT NULL` | `IS NOT NULL` | +| `EXISTS` | `EXISTS (subquery)` | +| `NOT EXISTS` | `NOT EXISTS (subquery)` | | `MATCH` | sqlite-vec vector nearest-neighbor search | +| `MATCH_BOOLEAN` | SQLite full-text search in boolean mode | **Example:** ```ts // Find users with email NOT NULL, ordered by created_at DESC, limit 20 -const res = await BunSQLite.select({ +const res = await NodeSQLite.select({ table: "users", query: { query: { @@ -597,7 +605,7 @@ const res = await BunSQLite.select({ ### JOIN ```ts -const res = await BunSQLite.select({ +const res = await NodeSQLite.select({ table: "posts", query: { join: [ @@ -616,7 +624,7 @@ const res = await BunSQLite.select({ ## Vector Table Support -`@moduletrace/bun-sqlite` integrates with [`sqlite-vec`](https://github.com/asg017/sqlite-vec) for storing and querying vector embeddings. +`@moduletrace/nsqlite` integrates with [`sqlite-vec`](https://github.com/asg017/sqlite-vec) for storing and querying vector embeddings. ### Define a vector table in the schema @@ -652,16 +660,16 @@ const res = await BunSQLite.select({ ```bash # Initial sync -bunx bun-sqlite schema +npx bun-sqlite schema # Recreate vector tables (e.g. after changing vectorSize) -bunx bun-sqlite schema --vector +npx bun-sqlite schema --vector ``` ### Query vectors ```ts -const res = await BunSQLite.select({ +const res = await NodeSQLite.select({ table: "documents", query: { query: { @@ -685,7 +693,7 @@ Run the `typedef` command (or pass `--typedef` to `schema`) to generate a `.ts` - A `const` array of all table names (`BunSQLiteTables`) - A `type` for each table (named `BUN_SQLITE__`) -- A union type `BUN_SQLITE__ALL_TYPEDEFS` +- An intersection type `BUN_SQLITE__ALL_TYPEDEFS` **Example output** (`db/types/db.ts`): @@ -704,16 +712,16 @@ export type BUN_SQLITE_MY_APP_USERS = { email?: string; }; -export type BUN_SQLITE_MY_APP_ALL_TYPEDEFS = BUN_SQLITE_MY_APP_USERS; +export type BUN_SQLITE_MY_APP_ALL_TYPEDEFS = BUN_SQLITE_MY_APP_USERS; // intersection of all table types ``` Use the generated types with the CRUD API for full type safety: ```ts -import BunSQLite from "@moduletrace/bun-sqlite"; +import NodeSQLite from "@moduletrace/nsqlite"; import { BUN_SQLITE_MY_APP_USERS, BunSQLiteTables } from "./db/types/db"; -const res = await BunSQLite.select({ +const res = await NodeSQLite.select({ table: "users" as (typeof BunSQLiteTables)[number], }); ``` @@ -735,27 +743,32 @@ Every table automatically receives the following fields — you do not need to d ## Project Structure ``` -bun-sqlite/ +node-sqlite/ ├── src/ -│ ├── index.ts # Main export (BunSQLite object) +│ ├── index.ts # Main export (NodeSQLite object) │ ├── commands/ │ │ ├── index.ts # CLI entry point │ │ ├── schema.ts # `schema` command │ │ ├── typedef.ts # `typedef` command │ │ ├── backup.ts # `backup` command │ │ └── restore.ts # `restore` command +│ ├── data/ +│ │ ├── app-data.ts # App-level constants (config filename, defaults) +│ │ └── grab-dir-names.ts # Directory name helpers │ ├── functions/ │ │ └── init.ts # Config + schema loader │ ├── lib/sqlite/ -│ │ ├── index.ts # Database client (bun:sqlite + sqlite-vec) +│ │ ├── index.ts # Database client (better-sqlite3 + sqlite-vec) │ │ ├── db-schema-manager.ts # Schema synchronization engine +│ │ ├── schema.ts # Internal schema reference │ │ ├── db-select.ts # Select implementation │ │ ├── db-insert.ts # Insert implementation │ │ ├── db-update.ts # Update implementation │ │ ├── db-delete.ts # Delete implementation │ │ ├── db-sql.ts # Raw SQL implementation │ │ ├── db-generate-type-defs.ts # Type def generator -│ │ └── schema-to-typedef.ts # Schema-to-TypeScript converter +│ │ ├── db-schema-to-typedef.ts # Schema-to-TypeScript converter (main) +│ │ └── schema-to-typedef.ts # Schema-to-TypeScript converter (legacy) │ ├── types/ │ │ └── index.ts # All TypeScript types and interfaces │ └── utils/ @@ -770,16 +783,20 @@ bun-sqlite/ │ ├── grab-backup-data.ts # Parse metadata from a backup filename │ └── trim-backups.ts # Prune oldest backups over max_backups └── test/ - └── test-01/ # Example project using the library + ├── test-01/ # Basic example project + │ ├── bun-sqlite.config.ts + │ ├── db/ + │ │ ├── bun-sqlite-schema.ts + │ │ └── types/bun-sqlite.ts # Generated types + │ └── src/ + │ └── sql.ts + └── test-02/ # Full CRUD example project ├── bun-sqlite.config.ts - ├── db/ - │ ├── bun-sqlite-schema.ts - │ └── types/bun-sqlite.ts # Generated types - └── src/ + ├── index.ts + └── src/crud/ ├── insert.ts ├── select.ts - ├── delete.ts - └── sql.ts + └── update.ts ``` --- diff --git a/package.json b/package.json index b39363d..65df7a4 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "@moduletrace/nsqlite", - "version": "1.0.8", - "description": "SQLite manager for Bun", + "version": "1.0.1", + "description": "SQLite manager for Node JS", "author": "Benjamin Toby", "main": "dist/index.js", "bin": {