@expressive/sql 0.4.4 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +54 -0
- package/dist/bin.d.ts +1 -0
- package/dist/bin.js +9 -0
- package/dist/bin.js.map +1 -0
- package/dist/cli.d.ts +6 -0
- package/dist/cli.js +80 -0
- package/dist/cli.js.map +1 -0
- package/dist/columns/Bool.d.ts +37 -0
- package/dist/columns/Bool.js +28 -0
- package/dist/columns/Bool.js.map +1 -0
- package/dist/columns/Num.d.ts +59 -0
- package/dist/columns/Num.js +42 -0
- package/dist/columns/Num.js.map +1 -0
- package/dist/columns/One.d.ts +25 -0
- package/dist/columns/One.js +15 -0
- package/dist/columns/One.js.map +1 -0
- package/dist/columns/Str.d.ts +36 -0
- package/dist/columns/Str.js +21 -0
- package/dist/columns/Str.js.map +1 -0
- package/dist/columns/Time.d.ts +52 -0
- package/dist/columns/Time.js +45 -0
- package/dist/columns/Time.js.map +1 -0
- package/dist/connection/Connection.d.ts +61 -0
- package/dist/connection/Connection.js +104 -0
- package/dist/connection/Connection.js.map +1 -0
- package/dist/connection/Generator.d.ts +68 -0
- package/dist/connection/Generator.js +242 -0
- package/dist/connection/Generator.js.map +1 -0
- package/dist/datatypes.d.ts +102 -0
- package/dist/datatypes.js +47 -0
- package/dist/datatypes.js.map +1 -0
- package/dist/dispatch.d.ts +6 -0
- package/dist/dispatch.js +44 -0
- package/dist/dispatch.js.map +1 -0
- package/dist/index.d.ts +12 -692
- package/dist/index.js +13 -1092
- package/dist/sqlite/SQLiteConnection.d.ts +83 -0
- package/dist/sqlite/SQLiteConnection.js +395 -0
- package/dist/sqlite/SQLiteConnection.js.map +1 -0
- package/dist/sqlite/SQLiteGenerator.d.ts +15 -0
- package/dist/sqlite/SQLiteGenerator.js +54 -0
- package/dist/sqlite/SQLiteGenerator.js.map +1 -0
- package/dist/sqlite/engine.d.ts +47 -0
- package/dist/sqlite/engine.js +104 -0
- package/dist/sqlite/engine.js.map +1 -0
- package/dist/utils.d.ts +5 -0
- package/dist/utils.js +8 -0
- package/dist/utils.js.map +1 -0
- package/package.json +64 -11
- package/skills/expressive-sql/SKILL.md +136 -0
- package/dist/index.d.mts +0 -692
- package/dist/index.mjs +0 -1052
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
//#region src/sqlite/engine.d.ts
|
|
2
|
+
/**
|
|
3
|
+
* A SQLite host - what `SQLiteConnection` runs statements on.
|
|
4
|
+
*
|
|
5
|
+
* Pass one in place of a filename for a SQLite the built-in loader cannot open.
|
|
6
|
+
* It is used as given - foreign keys are not switched on, and the connection's `close()` leaves it open.
|
|
7
|
+
*/
|
|
8
|
+
interface Engine extends Engine.Statements {
|
|
9
|
+
/** Release the database. Called only on an engine the connection opened. */
|
|
10
|
+
close(): Promise<void>;
|
|
11
|
+
/**
|
|
12
|
+
* Open a transaction on its own session.
|
|
13
|
+
*
|
|
14
|
+
* Without it the connection issues `BEGIN`, `COMMIT` and `ROLLBACK` through `exec`.
|
|
15
|
+
*/
|
|
16
|
+
transaction?(): Promise<Engine.Session>;
|
|
17
|
+
/**
|
|
18
|
+
* Run statements atomically.
|
|
19
|
+
*
|
|
20
|
+
* `sync` applies through it when present; a table rebuild then needs foreign keys off.
|
|
21
|
+
*/
|
|
22
|
+
batch?(sql: string[]): Promise<void>;
|
|
23
|
+
}
|
|
24
|
+
declare namespace Engine {
|
|
25
|
+
/** Statement methods an engine and a session share. Parameters are positional. */
|
|
26
|
+
interface Statements {
|
|
27
|
+
/** Run a statement, resolving every row. */
|
|
28
|
+
all(sql: string, params?: any[]): Promise<any[]>;
|
|
29
|
+
/** Run a statement, resolving the first row. */
|
|
30
|
+
get(sql: string, params?: any[]): Promise<any>;
|
|
31
|
+
/** Run a statement, resolving how many rows changed. */
|
|
32
|
+
run(sql: string, params?: any[]): Promise<{
|
|
33
|
+
changes: number;
|
|
34
|
+
}>;
|
|
35
|
+
/** Run one or more statements without parameters. */
|
|
36
|
+
exec(sql: string): Promise<void>;
|
|
37
|
+
}
|
|
38
|
+
/** A transaction's own handle - statements inside `db.transaction(fn)` run on it. */
|
|
39
|
+
interface Session extends Statements {
|
|
40
|
+
commit(): Promise<void>;
|
|
41
|
+
rollback(): Promise<void>;
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
declare function createEngine(filename: string): Promise<Engine>;
|
|
45
|
+
//#endregion
|
|
46
|
+
export { Engine, createEngine };
|
|
47
|
+
//# sourceMappingURL=engine.d.ts.map
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
//#region src/sqlite/engine.ts
|
|
2
|
+
const DRIVERS = [
|
|
3
|
+
bunSqlite,
|
|
4
|
+
nodeSqlite,
|
|
5
|
+
betterSqlite3,
|
|
6
|
+
sqlite3,
|
|
7
|
+
libsql
|
|
8
|
+
];
|
|
9
|
+
async function createEngine(filename) {
|
|
10
|
+
for (const load of DRIVERS) {
|
|
11
|
+
const engine = await load(filename).catch(() => null);
|
|
12
|
+
if (engine) {
|
|
13
|
+
await engine.exec("PRAGMA foreign_keys = ON");
|
|
14
|
+
return engine;
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
throw new Error("No compatible SQLite driver found. Run under Bun or Node >=24, or install one of: better-sqlite3, sqlite3, @libsql/client.");
|
|
18
|
+
}
|
|
19
|
+
function optional(name) {
|
|
20
|
+
return import(name);
|
|
21
|
+
}
|
|
22
|
+
async function bunSqlite(file) {
|
|
23
|
+
if (typeof globalThis.Bun === "undefined") return null;
|
|
24
|
+
const { Database } = await optional("bun:sqlite");
|
|
25
|
+
return syncEngine(new Database(file));
|
|
26
|
+
}
|
|
27
|
+
async function nodeSqlite(file) {
|
|
28
|
+
const { DatabaseSync } = await optional("node:sqlite");
|
|
29
|
+
return syncEngine(new DatabaseSync(file));
|
|
30
|
+
}
|
|
31
|
+
async function betterSqlite3(file) {
|
|
32
|
+
const { default: Database } = await optional("better-sqlite3");
|
|
33
|
+
return syncEngine(new Database(file));
|
|
34
|
+
}
|
|
35
|
+
async function sqlite3(file) {
|
|
36
|
+
const { default: { Database } } = await optional("sqlite3");
|
|
37
|
+
return asyncEngine(new Database(file));
|
|
38
|
+
}
|
|
39
|
+
async function libsql(file) {
|
|
40
|
+
const { createClient } = await optional("@libsql/client");
|
|
41
|
+
return libsqlEngine(createClient({ url: file === ":memory:" ? ":memory:" : `file:${file}` }));
|
|
42
|
+
}
|
|
43
|
+
function syncEngine(db) {
|
|
44
|
+
return {
|
|
45
|
+
async all(sql, params = []) {
|
|
46
|
+
return db.prepare(sql).all(...params);
|
|
47
|
+
},
|
|
48
|
+
async get(sql, params = []) {
|
|
49
|
+
return db.prepare(sql).get(...params);
|
|
50
|
+
},
|
|
51
|
+
async run(sql, params = []) {
|
|
52
|
+
return { changes: db.prepare(sql).run(...params).changes };
|
|
53
|
+
},
|
|
54
|
+
async exec(sql) {
|
|
55
|
+
db.exec(sql);
|
|
56
|
+
},
|
|
57
|
+
async close() {
|
|
58
|
+
db.close();
|
|
59
|
+
}
|
|
60
|
+
};
|
|
61
|
+
}
|
|
62
|
+
function asyncEngine(db) {
|
|
63
|
+
const call = (method, sql, params) => new Promise((resolve, reject) => {
|
|
64
|
+
db[method](sql, params, function(err, rows) {
|
|
65
|
+
if (err) reject(err);
|
|
66
|
+
else resolve(method === "run" ? this : rows);
|
|
67
|
+
});
|
|
68
|
+
});
|
|
69
|
+
const done = (resolve, reject) => (err) => err ? reject(err) : resolve();
|
|
70
|
+
return {
|
|
71
|
+
all: (sql, params = []) => call("all", sql, params),
|
|
72
|
+
get: (sql, params = []) => call("get", sql, params),
|
|
73
|
+
run: (sql, params = []) => call("run", sql, params).then((ctx) => ({ changes: ctx.changes })),
|
|
74
|
+
exec: (sql) => new Promise((resolve, reject) => db.exec(sql, done(resolve, reject))),
|
|
75
|
+
close: () => new Promise((resolve, reject) => db.close(done(resolve, reject)))
|
|
76
|
+
};
|
|
77
|
+
}
|
|
78
|
+
function libsqlEngine(client) {
|
|
79
|
+
const execute = (sql, args) => client.execute({
|
|
80
|
+
sql,
|
|
81
|
+
args
|
|
82
|
+
});
|
|
83
|
+
return {
|
|
84
|
+
async all(sql, params = []) {
|
|
85
|
+
return (await execute(sql, params)).rows;
|
|
86
|
+
},
|
|
87
|
+
async get(sql, params = []) {
|
|
88
|
+
return (await execute(sql, params)).rows[0];
|
|
89
|
+
},
|
|
90
|
+
async run(sql, params = []) {
|
|
91
|
+
return { changes: Number((await execute(sql, params)).rowsAffected) };
|
|
92
|
+
},
|
|
93
|
+
async exec(sql) {
|
|
94
|
+
await client.executeMultiple(sql);
|
|
95
|
+
},
|
|
96
|
+
async close() {
|
|
97
|
+
client.close();
|
|
98
|
+
}
|
|
99
|
+
};
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
//#endregion
|
|
103
|
+
export { createEngine };
|
|
104
|
+
//# sourceMappingURL=engine.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"engine.js","names":[],"sources":["../../src/sqlite/engine.ts"],"sourcesContent":["/**\n * A SQLite host - what `SQLiteConnection` runs statements on.\n *\n * Pass one in place of a filename for a SQLite the built-in loader cannot open.\n * It is used as given - foreign keys are not switched on, and the connection's `close()` leaves it open.\n */\nexport interface Engine extends Engine.Statements {\n /** Release the database. Called only on an engine the connection opened. */\n close(): Promise<void>;\n /**\n * Open a transaction on its own session.\n *\n * Without it the connection issues `BEGIN`, `COMMIT` and `ROLLBACK` through `exec`.\n */\n transaction?(): Promise<Engine.Session>;\n /**\n * Run statements atomically.\n *\n * `sync` applies through it when present; a table rebuild then needs foreign keys off.\n */\n batch?(sql: string[]): Promise<void>;\n}\n\nexport declare namespace Engine {\n /** Statement methods an engine and a session share. Parameters are positional. */\n interface Statements {\n /** Run a statement, resolving every row. */\n all(sql: string, params?: any[]): Promise<any[]>;\n /** Run a statement, resolving the first row. */\n get(sql: string, params?: any[]): Promise<any>;\n /** Run a statement, resolving how many rows changed. */\n run(sql: string, params?: any[]): Promise<{ changes: number }>;\n /** Run one or more statements without parameters. */\n exec(sql: string): Promise<void>;\n }\n\n /** A transaction's own handle - statements inside `db.transaction(fn)` run on it. */\n interface Session extends Statements {\n commit(): Promise<void>;\n rollback(): Promise<void>;\n }\n}\n\nconst DRIVERS = [bunSqlite, nodeSqlite, betterSqlite3, sqlite3, libsql];\n\nexport async function createEngine(filename: string): Promise<Engine> {\n for (const load of DRIVERS) {\n const engine = await load(filename).catch(() => null);\n\n if (engine) {\n await engine.exec(\"PRAGMA foreign_keys = ON\");\n return engine;\n }\n }\n\n throw new Error(\n \"No compatible SQLite driver found. Run under Bun or Node >=24, \" +\n \"or install one of: better-sqlite3, sqlite3, @libsql/client.\"\n );\n}\n\nfunction optional(name: string): Promise<any> {\n return import(name);\n}\n\nasync function bunSqlite(file: string): Promise<Engine | null> {\n if (typeof (globalThis as any).Bun === \"undefined\")\n return null;\n\n const { Database } = await optional(\"bun:sqlite\");\n\n return syncEngine(new Database(file));\n}\n\nasync function nodeSqlite(file: string): Promise<Engine | null> {\n const { DatabaseSync } = await optional(\"node:sqlite\");\n\n return syncEngine(new DatabaseSync(file));\n}\n\nasync function betterSqlite3(file: string): Promise<Engine | null> {\n const { default: Database } = await optional(\"better-sqlite3\");\n\n return syncEngine(new Database(file));\n}\n\nasync function sqlite3(file: string): Promise<Engine | null> {\n const { default: { Database } } = await optional(\"sqlite3\");\n\n return asyncEngine(new Database(file));\n}\n\nasync function libsql(file: string): Promise<Engine | null> {\n const { createClient } = await optional(\"@libsql/client\");\n const url = file === \":memory:\" ? \":memory:\" : `file:${file}`;\n\n return libsqlEngine(createClient({ url }));\n}\n\nfunction syncEngine(db: any): Engine {\n return {\n async all(sql, params = []) {\n return db.prepare(sql).all(...params);\n },\n async get(sql, params = []) {\n return db.prepare(sql).get(...params);\n },\n async run(sql, params = []) {\n return { changes: db.prepare(sql).run(...params).changes };\n },\n async exec(sql) {\n db.exec(sql);\n },\n async close() {\n db.close();\n }\n };\n}\n\nfunction asyncEngine(db: any): Engine {\n const call = (method: string, sql: string, params: any[]) =>\n new Promise<any>((resolve, reject) => {\n db[method](sql, params, function (this: any, err: any, rows: any) {\n if (err) reject(err);\n else resolve(method === \"run\" ? this : rows);\n });\n });\n\n const done = (resolve: () => void, reject: (err: any) => void) =>\n (err: any) => err ? reject(err) : resolve();\n\n return {\n all: (sql, params = []) => call(\"all\", sql, params),\n get: (sql, params = []) => call(\"get\", sql, params),\n run: (sql, params = []) => call(\"run\", sql, params).then(ctx => ({ changes: ctx.changes })),\n exec: sql => new Promise((resolve, reject) => db.exec(sql, done(resolve, reject))),\n close: () => new Promise((resolve, reject) => db.close(done(resolve, reject)))\n };\n}\n\nfunction libsqlEngine(client: any): Engine {\n const execute = (sql: string, args: any[]) => client.execute({ sql, args });\n\n return {\n async all(sql, params = []) {\n return (await execute(sql, params)).rows;\n },\n async get(sql, params = []) {\n return (await execute(sql, params)).rows[0];\n },\n async run(sql, params = []) {\n return { changes: Number((await execute(sql, params)).rowsAffected) };\n },\n async exec(sql) {\n await client.executeMultiple(sql);\n },\n async close() {\n client.close();\n }\n };\n}\n"],"mappings":"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"}
|
package/dist/utils.d.ts
ADDED
package/dist/utils.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"utils.js","names":[],"sources":["../src/utils.ts"],"sourcesContent":["export function escape(value: unknown){\n return typeof value == \"string\"\n ? `'${value.replace(/'/g, \"''\")}'`\n : value;\n}\n"],"mappings":";AAAA,SAAgB,OAAO,OAAe;AACpC,QAAO,OAAO,SAAS,WACnB,IAAI,MAAM,QAAQ,MAAM,KAAK,CAAC,KAC9B"}
|
package/package.json
CHANGED
|
@@ -1,8 +1,28 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@expressive/sql",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Query
|
|
3
|
+
"version": "0.6.0",
|
|
4
|
+
"description": "Expressive ORM on SQL: entities, Query and an embedded SQLite store from one import.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"orm",
|
|
7
|
+
"sql",
|
|
8
|
+
"sqlite",
|
|
9
|
+
"entity",
|
|
10
|
+
"reactive",
|
|
11
|
+
"query-builder",
|
|
12
|
+
"expressive",
|
|
13
|
+
"mvc"
|
|
14
|
+
],
|
|
5
15
|
"license": "ISC",
|
|
16
|
+
"repository": {
|
|
17
|
+
"type": "git",
|
|
18
|
+
"url": "git+https://github.com/gabeklein/expressive-orm.git",
|
|
19
|
+
"directory": "packages/sql"
|
|
20
|
+
},
|
|
21
|
+
"homepage": "https://github.com/gabeklein/expressive-orm/tree/main/packages/sql#readme",
|
|
22
|
+
"bugs": {
|
|
23
|
+
"url": "https://github.com/gabeklein/expressive-orm/issues"
|
|
24
|
+
},
|
|
25
|
+
"type": "module",
|
|
6
26
|
"publishConfig": {
|
|
7
27
|
"access": "public"
|
|
8
28
|
},
|
|
@@ -11,20 +31,53 @@
|
|
|
11
31
|
"email": "gabe@expressive.dev",
|
|
12
32
|
"url": "https://github.com/gabeklein"
|
|
13
33
|
},
|
|
14
|
-
"main": "dist",
|
|
15
|
-
"
|
|
34
|
+
"main": "dist/index.js",
|
|
35
|
+
"types": "dist/index.d.ts",
|
|
36
|
+
"exports": {
|
|
37
|
+
".": {
|
|
38
|
+
"types": "./dist/index.d.ts",
|
|
39
|
+
"default": "./dist/index.js"
|
|
40
|
+
}
|
|
41
|
+
},
|
|
42
|
+
"bin": {
|
|
43
|
+
"expressive": "./dist/bin.js"
|
|
44
|
+
},
|
|
45
|
+
"expressive": {
|
|
46
|
+
"bin": "./dist/cli.js"
|
|
47
|
+
},
|
|
16
48
|
"files": [
|
|
17
|
-
"dist"
|
|
49
|
+
"dist",
|
|
50
|
+
"skills"
|
|
18
51
|
],
|
|
52
|
+
"scripts": {
|
|
53
|
+
"build": "tsdown",
|
|
54
|
+
"typecheck": "tsc --noEmit --incremental",
|
|
55
|
+
"coverage": "vitest run --coverage",
|
|
56
|
+
"test": "bun run typecheck && bun run coverage"
|
|
57
|
+
},
|
|
19
58
|
"dependencies": {
|
|
59
|
+
"@expressive/orm": "^0.14.0",
|
|
20
60
|
"sql-formatter": "^10.7.2"
|
|
21
61
|
},
|
|
22
62
|
"devDependencies": {
|
|
23
|
-
"
|
|
63
|
+
"@expressive/mvc": "^0.94.2",
|
|
64
|
+
"tsdown": "^0.20.1"
|
|
24
65
|
},
|
|
25
|
-
"
|
|
26
|
-
"
|
|
27
|
-
"
|
|
28
|
-
"
|
|
66
|
+
"peerDependencies": {
|
|
67
|
+
"@expressive/mvc": "^0.94.0",
|
|
68
|
+
"@libsql/client": ">=0.5.0",
|
|
69
|
+
"better-sqlite3": ">=11.0.0",
|
|
70
|
+
"sqlite3": ">=5.0.0"
|
|
71
|
+
},
|
|
72
|
+
"peerDependenciesMeta": {
|
|
73
|
+
"@libsql/client": {
|
|
74
|
+
"optional": true
|
|
75
|
+
},
|
|
76
|
+
"better-sqlite3": {
|
|
77
|
+
"optional": true
|
|
78
|
+
},
|
|
79
|
+
"sqlite3": {
|
|
80
|
+
"optional": true
|
|
81
|
+
}
|
|
29
82
|
}
|
|
30
|
-
}
|
|
83
|
+
}
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: expressive-sql
|
|
3
|
+
description: Expressive ORM on SQL (@expressive/sql) - SQLiteConnection with a built-in or custom Engine, sync and plan, the expressive sql CLI, the sql.* datatype vocabulary and validation, and the SQL Connection and Generator base for dialects. Use when connecting entities to SQLite, choosing column datatypes, syncing or checking a schema, plugging in a SQLite host, or writing a SQL driver.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# @expressive/sql
|
|
7
|
+
|
|
8
|
+
Expressive ORM on SQL, with embedded SQLite. Re-exports `@expressive/orm` - entities, fields, relations, `Query` and transactions are in `expressive-orm`. Apps import everything from `@expressive/sql`; driver seams come from `@expressive/orm/driver`.
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
npm install @expressive/sql @expressive/mvc
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
SQLite is built into Bun (`bun:sqlite`) and Node 24 (`node:sqlite`). Elsewhere add one of `better-sqlite3`, `sqlite3` or `@libsql/client`; the first found is used. For Postgres and live rows install `@expressive/postgres` (skill `expressive-postgres`), which re-exports this package.
|
|
15
|
+
|
|
16
|
+
## Connect
|
|
17
|
+
|
|
18
|
+
```ts
|
|
19
|
+
import { SQLiteConnection, Type, str } from '@expressive/sql';
|
|
20
|
+
|
|
21
|
+
class User extends Type {
|
|
22
|
+
name = str();
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
const db = await SQLiteConnection.new([User], "app.db"); // omit the filename for in-memory
|
|
26
|
+
|
|
27
|
+
await db.close();
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Connections enforce foreign keys. SQLite has no live rows.
|
|
31
|
+
|
|
32
|
+
`sync` covers the classes passed to `new`. `static connection = db` binds another class without syncing it. `db.schema` is the DDL.
|
|
33
|
+
|
|
34
|
+
### Engine
|
|
35
|
+
|
|
36
|
+
In place of the filename, pass an `Engine` for a SQLite the built-in loader can't open - any object with these, each async:
|
|
37
|
+
|
|
38
|
+
```ts
|
|
39
|
+
import type { Engine } from '@expressive/sql';
|
|
40
|
+
|
|
41
|
+
const engine: Engine = {
|
|
42
|
+
all: (sql, params) => ..., // rows
|
|
43
|
+
get: (sql, params) => ..., // first row
|
|
44
|
+
run: (sql, params) => ..., // { changes }
|
|
45
|
+
exec: (sql) => ...,
|
|
46
|
+
close: () => ...,
|
|
47
|
+
};
|
|
48
|
+
|
|
49
|
+
const db = await SQLiteConnection.new([User], engine);
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
A given engine is used as is - turn on foreign keys yourself where the host doesn't - and `close()` leaves it open.
|
|
53
|
+
|
|
54
|
+
Two optional members, for hosts without `BEGIN` and `COMMIT` on one connection:
|
|
55
|
+
|
|
56
|
+
- `transaction()` - resolves a session, the four statements plus `commit()` and `rollback()`. Every statement inside `db.transaction(fn)` runs on it.
|
|
57
|
+
- `batch(sql: string[])` - runs statements atomically; `sync` applies through it. A table rebuild in a batch needs foreign keys off, or dropping the old table cascades; an engine that keeps them on refuses it.
|
|
58
|
+
|
|
59
|
+
## Sync
|
|
60
|
+
|
|
61
|
+
Awaiting a connection runs `sync`:
|
|
62
|
+
|
|
63
|
+
- Missing tables are created, missing columns and indexes added, existing ones checked against the classes.
|
|
64
|
+
- A new column reads `undefined` or its `fallback` on old rows. One that cannot fill existing rows - primary, `UNIQUE`, `NOT NULL` without a `fallback` or defaulting to now - is reported and nothing changes. A nullable column defaulting to now is added without the default; inserts fill it.
|
|
65
|
+
- Type and nullability drift is reported. `sync(true, true)` rebuilds the table, refusing while a row would not fit or a value would not convert. A rebuild keeps columns not on the class, indexes and triggers, but not UNIQUE or REFERENCES on columns the class doesn't declare, and refuses while any row references a missing one.
|
|
66
|
+
- `static schema` is reported - SQLite has none.
|
|
67
|
+
- A relation column missing while `<table>_id` exists is reported, not added - set `{ column: "<table>_id" }` to keep the old one.
|
|
68
|
+
- `sync(false)` only verifies. `plan(force?)` returns `{ steps, problems }` - each step with `action`, `reason` and `sql` - without doing it. A sync applies in one transaction.
|
|
69
|
+
|
|
70
|
+
### Command line
|
|
71
|
+
|
|
72
|
+
```sh
|
|
73
|
+
expressive sql check src/db.ts # list what sync would change; exit 1 if anything would
|
|
74
|
+
expressive sql sync src/db.ts # create missing tables, columns and indexes
|
|
75
|
+
expressive sql sync --force src/db.ts # also rebuild drifted columns
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
The entry is the module that creates the connections - imported with `sync` held back, so `await Connection.new()` resolves without touching the database; the command plans and syncs each connection created. A TypeScript entry needs Bun (`bunx --bun expressive ...`) or Node 22.18+.
|
|
79
|
+
|
|
80
|
+
## Datatypes
|
|
81
|
+
|
|
82
|
+
`sql.*` picks a column's type; a factory takes its size. A config is portable - the same class syncs on SQLite and Postgres.
|
|
83
|
+
|
|
84
|
+
| Helper | `sql.*` | SQLite |
|
|
85
|
+
|---|---|---|
|
|
86
|
+
| `str` | `text` (default), `varchar(n)`, `char(n)`, `uuid` | TEXT |
|
|
87
|
+
| `num` | `integer` (default), `smallint`, `bigint`, `real`, `float`, `double`, `numeric(p, s)`, `decimal(p, s)` | INTEGER, REAL, NUMERIC |
|
|
88
|
+
| `bool` | `boolean` (default), `integer` (1/0), `text` / `varchar(n)` with `either` | INTEGER, TEXT |
|
|
89
|
+
| `date` | `timestamp` (default), `date`, `time`, `ms` (epoch ms), `seconds` or `integer` (epoch s), `text` | TEXT, INTEGER |
|
|
90
|
+
| `one` | `integer` (default), `bigint` | INTEGER |
|
|
91
|
+
|
|
92
|
+
```ts
|
|
93
|
+
import { Type, bool, date, key, num, sql, str } from '@expressive/sql';
|
|
94
|
+
|
|
95
|
+
class Product extends Type {
|
|
96
|
+
id = key(sql.uuid); // UUIDv7 on insert
|
|
97
|
+
code = str(sql.char(3));
|
|
98
|
+
price = num(sql.numeric(10, 2));
|
|
99
|
+
listed = bool(sql.text, { either: ["yes", "no"] });
|
|
100
|
+
seen = date(sql.ms, null);
|
|
101
|
+
edited = date.updated(sql.ms);
|
|
102
|
+
}
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
- `num()` is a 32-bit integer - a fraction or a value outside 32-bit range throws on write. `sql.bigint` for large integers, `sql.real` or `sql.numeric(p, s)` for fractions.
|
|
106
|
+
- A datatype of another helper, like `num(sql.text)`, is a type error.
|
|
107
|
+
- Options a factory doesn't take go in an object - `date({ type: "timestamp", precision: 3 })`.
|
|
108
|
+
- `sql.now` is the database's current time in the column's storage - as a `fallback`, in a statics write or comparison (`lessThan(sql.now)`), or in a `Query`. Statics read it from the app's clock. `"NOW"` is a deprecated alias.
|
|
109
|
+
- Writes are validated - `varchar` and `char` length, integer ranges, `numeric` precision and scale. Importing `@expressive/sql` turns this on for every connection, `memory()` included.
|
|
110
|
+
|
|
111
|
+
Add a datatype by augmenting the helper's `Types`:
|
|
112
|
+
|
|
113
|
+
```ts
|
|
114
|
+
import { StringColumn, Type, str } from '@expressive/sql';
|
|
115
|
+
|
|
116
|
+
declare module '@expressive/orm' {
|
|
117
|
+
namespace str {
|
|
118
|
+
interface Inet extends StringColumn { type: "inet" }
|
|
119
|
+
interface Types { inet: Inet }
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
class Device extends Type {
|
|
124
|
+
address = str({ type: "inet" });
|
|
125
|
+
}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
`StringColumn`, `NumericColumn`, `BooleanColumn`, `TimeColumn`, `ForeignColumn` are the column classes behind `str`, `num`, `bool`, `date` and `one`.
|
|
129
|
+
|
|
130
|
+
## SQL drivers
|
|
131
|
+
|
|
132
|
+
`Connection` from `@expressive/sql` implements orm's floor over `Query`. A dialect extends it and supplies `schema`, `prepare(builder)` (rendering with a `Generator` subclass), `sync(fix?, force?)` and `plan(force?)`; a protected `transact(fn)` enables `transaction(fn)`.
|
|
133
|
+
|
|
134
|
+
`Generator` renders a `Query` builder as SQL; `String(generator)` is the statement. A dialect overrides its protected hooks - `literal`, `insertWith`, `table`, `now` and `param` among them, each documented on `Generator`.
|
|
135
|
+
|
|
136
|
+
The builder and its values - `Builder`, `DataTable`, `DataField`, `Parameter`, `Computed`, `QueryTemplate`, `Where` - import from `@expressive/orm/driver`, not `@expressive/sql`. A dialect package therefore lists `@expressive/orm` as a direct dependency, at the range `@expressive/sql` depends on.
|