@expressive/sql 0.5.0 → 0.7.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 +4 -3
- package/dist/columns/Bool.d.ts +1 -0
- package/dist/columns/Bool.js +1 -0
- package/dist/columns/Bool.js.map +1 -1
- package/dist/columns/Num.d.ts +5 -0
- package/dist/columns/Num.js +5 -0
- package/dist/columns/Num.js.map +1 -1
- package/dist/columns/One.d.ts +1 -0
- package/dist/columns/One.js +1 -0
- package/dist/columns/One.js.map +1 -1
- package/dist/columns/Str.d.ts +1 -0
- package/dist/columns/Str.js +1 -0
- package/dist/columns/Str.js.map +1 -1
- package/dist/columns/Time.d.ts +5 -0
- package/dist/columns/Time.js +5 -0
- package/dist/columns/Time.js.map +1 -1
- package/dist/connection/Connection.d.ts +32 -14
- package/dist/connection/Connection.js +10 -48
- package/dist/connection/Connection.js.map +1 -1
- package/dist/connection/Generator.d.ts +40 -4
- package/dist/connection/Generator.js +55 -22
- package/dist/connection/Generator.js.map +1 -1
- package/dist/datatypes.d.ts +38 -5
- package/dist/datatypes.js +5 -0
- package/dist/datatypes.js.map +1 -1
- package/dist/index.d.ts +2 -1
- package/dist/sqlite/SQLiteConnection.d.ts +42 -3
- package/dist/sqlite/SQLiteConnection.js +89 -22
- package/dist/sqlite/SQLiteConnection.js.map +1 -1
- package/dist/sqlite/SQLiteGenerator.d.ts +2 -1
- package/dist/sqlite/SQLiteGenerator.js.map +1 -1
- package/dist/sqlite/engine.d.ts +80 -8
- package/dist/sqlite/engine.js +58 -6
- package/dist/sqlite/engine.js.map +1 -1
- package/package.json +8 -5
- package/skills/expressive-sql/SKILL.md +168 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@expressive/sql",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.0",
|
|
4
4
|
"description": "Expressive ORM on SQL: entities, Query and an embedded SQLite store from one import.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"orm",
|
|
@@ -46,7 +46,8 @@
|
|
|
46
46
|
"bin": "./dist/cli.js"
|
|
47
47
|
},
|
|
48
48
|
"files": [
|
|
49
|
-
"dist"
|
|
49
|
+
"dist",
|
|
50
|
+
"skills"
|
|
50
51
|
],
|
|
51
52
|
"scripts": {
|
|
52
53
|
"build": "tsdown",
|
|
@@ -55,16 +56,18 @@
|
|
|
55
56
|
"test": "bun run typecheck && bun run coverage"
|
|
56
57
|
},
|
|
57
58
|
"dependencies": {
|
|
58
|
-
"@expressive/orm": "^0.
|
|
59
|
+
"@expressive/orm": "^0.14.0",
|
|
59
60
|
"sql-formatter": "^10.7.2"
|
|
60
61
|
},
|
|
61
62
|
"devDependencies": {
|
|
62
|
-
"@expressive/mvc": "^0.94.
|
|
63
|
+
"@expressive/mvc": "^0.94.2",
|
|
64
|
+
"@libsql/client": "^0.18.0",
|
|
65
|
+
"miniflare": "^4.20260730.0",
|
|
63
66
|
"tsdown": "^0.20.1"
|
|
64
67
|
},
|
|
65
68
|
"peerDependencies": {
|
|
66
69
|
"@expressive/mvc": "^0.94.0",
|
|
67
|
-
"@libsql/client": ">=0.
|
|
70
|
+
"@libsql/client": ">=0.18.0",
|
|
68
71
|
"better-sqlite3": ">=11.0.0",
|
|
69
72
|
"sqlite3": ">=5.0.0"
|
|
70
73
|
},
|
|
@@ -0,0 +1,168 @@
|
|
|
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, Cloudflare D1 or libSQL and Turso, 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` (0.18 or later); 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
|
+
### Hosts
|
|
60
|
+
|
|
61
|
+
In place of the filename, `new` also takes a D1 binding, a libSQL `Client` or a libSQL address, told apart by shape. A given binding or client is used as is; `close()` leaves it open.
|
|
62
|
+
|
|
63
|
+
On Workers, open once from the first request's binding, and drop it when `sync` fails - a second `new` while entities hold a connection throws:
|
|
64
|
+
|
|
65
|
+
```ts
|
|
66
|
+
let ready: Promise<unknown> | undefined;
|
|
67
|
+
|
|
68
|
+
function open(DB: D1Database){
|
|
69
|
+
const db = SQLiteConnection.new([User], DB);
|
|
70
|
+
|
|
71
|
+
return Promise.resolve(db).catch(async error => {
|
|
72
|
+
ready = undefined;
|
|
73
|
+
await db.close();
|
|
74
|
+
throw error;
|
|
75
|
+
});
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
export default {
|
|
79
|
+
async fetch(request: Request, env: { DB: D1Database }) {
|
|
80
|
+
await (ready ??= open(env.DB));
|
|
81
|
+
return Response.json(await User.find({}));
|
|
82
|
+
}
|
|
83
|
+
};
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
- D1 - `sync` applies as one batch, a few round trips per table each cold start. `transaction` throws. Foreign keys stay on, so `sync(true, true)` refuses a rebuild.
|
|
87
|
+
- libSQL address - `libsql:`, `https:`, `http:`, `ws:` or `wss:` opens `@libsql/client` 0.18+; token as `?authToken=`. Loaded at runtime, so under a bundler (Workers) pass a `createClient` client instead. An `undefined` or empty source opens in memory - check an address from the environment first.
|
|
88
|
+
- Every libSQL client - each `transaction` is a libSQL write transaction (`BEGIN IMMEDIATE`) holding the connection's lock, so transactions run one at a time app-wide. `sync` is one batch; a rebuild runs through `client.migrate`, foreign keys off for it alone. Local libSQL enforces foreign keys by default; remote gets the server's setting.
|
|
89
|
+
- A `migrate` rebuild refuses dangling rows (`foreign_key_check`) even where foreign keys are off, and leaves them on.
|
|
90
|
+
|
|
91
|
+
## Sync
|
|
92
|
+
|
|
93
|
+
Awaiting a connection runs `sync`:
|
|
94
|
+
|
|
95
|
+
- Missing tables are created, missing columns and indexes added, existing ones checked against the classes.
|
|
96
|
+
- 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.
|
|
97
|
+
- 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.
|
|
98
|
+
- `static schema` is reported - SQLite has none.
|
|
99
|
+
- A relation column missing while `<table>_id` exists is reported, not added - set `{ column: "<table>_id" }` to keep the old one.
|
|
100
|
+
- `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.
|
|
101
|
+
|
|
102
|
+
### Command line
|
|
103
|
+
|
|
104
|
+
```sh
|
|
105
|
+
expressive sql check src/db.ts # list what sync would change; exit 1 if anything would
|
|
106
|
+
expressive sql sync src/db.ts # create missing tables, columns and indexes
|
|
107
|
+
expressive sql sync --force src/db.ts # also rebuild drifted columns
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
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+.
|
|
111
|
+
|
|
112
|
+
## Datatypes
|
|
113
|
+
|
|
114
|
+
`sql.*` picks a column's type; a factory takes its size. A config is portable - the same class syncs on SQLite and Postgres.
|
|
115
|
+
|
|
116
|
+
| Helper | `sql.*` | SQLite |
|
|
117
|
+
|---|---|---|
|
|
118
|
+
| `str` | `text` (default), `varchar(n)`, `char(n)`, `uuid` | TEXT |
|
|
119
|
+
| `num` | `integer` (default), `smallint`, `bigint`, `real`, `float`, `double`, `numeric(p, s)`, `decimal(p, s)` | INTEGER, REAL, NUMERIC |
|
|
120
|
+
| `bool` | `boolean` (default), `integer` (1/0), `text` / `varchar(n)` with `either` | INTEGER, TEXT |
|
|
121
|
+
| `date` | `timestamp` (default), `date`, `time`, `ms` (epoch ms), `seconds` or `integer` (epoch s), `text` | TEXT, INTEGER |
|
|
122
|
+
| `one` | `integer` (default), `bigint` | INTEGER |
|
|
123
|
+
|
|
124
|
+
```ts
|
|
125
|
+
import { Type, bool, date, key, num, sql, str } from '@expressive/sql';
|
|
126
|
+
|
|
127
|
+
class Product extends Type {
|
|
128
|
+
id = key(sql.uuid); // UUIDv7 on insert
|
|
129
|
+
code = str(sql.char(3));
|
|
130
|
+
price = num(sql.numeric(10, 2));
|
|
131
|
+
listed = bool(sql.text, { either: ["yes", "no"] });
|
|
132
|
+
seen = date(sql.ms, null);
|
|
133
|
+
edited = date.updated(sql.ms);
|
|
134
|
+
}
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
- `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.
|
|
138
|
+
- A datatype of another helper, like `num(sql.text)`, is a type error.
|
|
139
|
+
- Options a factory doesn't take go in an object - `date({ type: "timestamp", precision: 3 })`.
|
|
140
|
+
- `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.
|
|
141
|
+
- Writes are validated - `varchar` and `char` length, integer ranges, `numeric` precision and scale. Importing `@expressive/sql` turns this on for every connection, `memory()` included.
|
|
142
|
+
|
|
143
|
+
Add a datatype by augmenting the helper's `Types`:
|
|
144
|
+
|
|
145
|
+
```ts
|
|
146
|
+
import { StringColumn, Type, str } from '@expressive/sql';
|
|
147
|
+
|
|
148
|
+
declare module '@expressive/orm' {
|
|
149
|
+
namespace str {
|
|
150
|
+
interface Inet extends StringColumn { type: "inet" }
|
|
151
|
+
interface Types { inet: Inet }
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
class Device extends Type {
|
|
156
|
+
address = str({ type: "inet" });
|
|
157
|
+
}
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
`StringColumn`, `NumericColumn`, `BooleanColumn`, `TimeColumn`, `ForeignColumn` are the column classes behind `str`, `num`, `bool`, `date` and `one`.
|
|
161
|
+
|
|
162
|
+
## SQL drivers
|
|
163
|
+
|
|
164
|
+
`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)`.
|
|
165
|
+
|
|
166
|
+
`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`.
|
|
167
|
+
|
|
168
|
+
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.
|