@expressive/sql 0.8.3 → 0.9.1
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 +1 -1
- package/dist/datatypes.d.ts +1 -1
- package/dist/datatypes.js +1 -1
- package/dist/datatypes.js.map +1 -1
- package/package.json +2 -2
- package/skills/expressive-sql/SKILL.md +24 -26
package/README.md
CHANGED
|
@@ -26,7 +26,7 @@ const db = await SQLiteConnection.new([User, Post], "app.db");
|
|
|
26
26
|
const gabe = await User.new({ name: "Gabe", age: 35 });
|
|
27
27
|
await Post.insert({ author: gabe, title: "Hello" });
|
|
28
28
|
|
|
29
|
-
const adults = await User.
|
|
29
|
+
const adults = await User.query({ age: greaterThan(17) });
|
|
30
30
|
|
|
31
31
|
const titles = await Query(where => {
|
|
32
32
|
const post = where(Post);
|
package/dist/datatypes.d.ts
CHANGED
|
@@ -72,7 +72,7 @@ interface Datatypes {
|
|
|
72
72
|
};
|
|
73
73
|
}
|
|
74
74
|
/**
|
|
75
|
-
* Column datatypes, passed to a field helper - `str(sql.varchar(255))`, `date(sql.
|
|
75
|
+
* Column datatypes, passed to a field helper - `str(sql.varchar(255))`, `date(sql.date)`.
|
|
76
76
|
*
|
|
77
77
|
* Each fits only the helpers named on it; elsewhere it is a type error.
|
|
78
78
|
*/
|
package/dist/datatypes.js
CHANGED
|
@@ -2,7 +2,7 @@ import { now } from "@expressive/orm";
|
|
|
2
2
|
|
|
3
3
|
//#region src/datatypes.ts
|
|
4
4
|
/**
|
|
5
|
-
* Column datatypes, passed to a field helper - `str(sql.varchar(255))`, `date(sql.
|
|
5
|
+
* Column datatypes, passed to a field helper - `str(sql.varchar(255))`, `date(sql.date)`.
|
|
6
6
|
*
|
|
7
7
|
* Each fits only the helpers named on it; elsewhere it is a type error.
|
|
8
8
|
*/
|
package/dist/datatypes.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"datatypes.js","names":[],"sources":["../src/datatypes.ts"],"sourcesContent":["import { now } from '@expressive/orm';\n\ninterface Datatypes {\n /** The current time - rendered by the database in the column's storage; statics take the app's clock. */\n readonly now: typeof now;\n /** `str` (default) - unbounded text. */\n readonly text: { readonly type: \"text\" };\n /** `str` - a UUID. As `key(sql.uuid)`, a UUIDv7 is generated on insert when absent. */\n readonly uuid: { readonly type: \"uuid\" };\n /** `num` (default) - 32-bit integer; a fraction or a value out of range throws on write. */\n readonly integer: { readonly type: \"integer\" };\n /** `num` - 16-bit integer; a fraction or a value out of range throws on write. */\n readonly smallint: { readonly type: \"smallint\" };\n /** `num` - 64-bit integer; a fraction throws on write. */\n readonly bigint: { readonly type: \"bigint\" };\n /** `num` - floating point. */\n readonly real: { readonly type: \"real\" };\n /** `num` - floating point, `double precision` in schema. */\n readonly double: { readonly type: \"double\" };\n /** `date` (default) - date and time. */\n readonly timestamp: { readonly type: \"timestamp\" };\n /** `date` - a calendar day, stored `YYYY-MM-DD` from the local day and read as local midnight. */\n readonly date: { readonly type: \"date\" };\n /** `date` - time of day, `HH:MM:SS` UTC, read on 1970-01-01. */\n readonly time: { readonly type: \"time\" };\n /** `str` - text up to `length` characters; longer throws on write. */\n readonly varchar: <N extends number>(length: N) => { readonly type: \"varchar\"; readonly length: N };\n /** `str` - fixed-length text; longer than `length` throws on write. */\n readonly char: <N extends number>(length: N) => { readonly type: \"char\"; readonly length: N };\n /**\n * `num` - exact decimal of `precision` digits, `scale` (default 0) after the point.\n *\n * A value past either throws on write.\n */\n readonly numeric: (precision: number, scale?: number) => { readonly type: \"numeric\"; readonly precision: number; readonly scale: number };\n /** `num` - exact decimal, as `numeric`. */\n readonly decimal: (precision: number, scale?: number) => { readonly type: \"decimal\"; readonly precision: number; readonly scale: number };\n}\n\n/**\n * Column datatypes, passed to a field helper - `str(sql.varchar(255))`, `date(sql.
|
|
1
|
+
{"version":3,"file":"datatypes.js","names":[],"sources":["../src/datatypes.ts"],"sourcesContent":["import { now } from '@expressive/orm';\n\ninterface Datatypes {\n /** The current time - rendered by the database in the column's storage; statics take the app's clock. */\n readonly now: typeof now;\n /** `str` (default) - unbounded text. */\n readonly text: { readonly type: \"text\" };\n /** `str` - a UUID. As `key(sql.uuid)`, a UUIDv7 is generated on insert when absent. */\n readonly uuid: { readonly type: \"uuid\" };\n /** `num` (default) - 32-bit integer; a fraction or a value out of range throws on write. */\n readonly integer: { readonly type: \"integer\" };\n /** `num` - 16-bit integer; a fraction or a value out of range throws on write. */\n readonly smallint: { readonly type: \"smallint\" };\n /** `num` - 64-bit integer; a fraction throws on write. */\n readonly bigint: { readonly type: \"bigint\" };\n /** `num` - floating point. */\n readonly real: { readonly type: \"real\" };\n /** `num` - floating point, `double precision` in schema. */\n readonly double: { readonly type: \"double\" };\n /** `date` (default) - date and time. */\n readonly timestamp: { readonly type: \"timestamp\" };\n /** `date` - a calendar day, stored `YYYY-MM-DD` from the local day and read as local midnight. */\n readonly date: { readonly type: \"date\" };\n /** `date` - time of day, `HH:MM:SS` UTC, read on 1970-01-01. */\n readonly time: { readonly type: \"time\" };\n /** `str` - text up to `length` characters; longer throws on write. */\n readonly varchar: <N extends number>(length: N) => { readonly type: \"varchar\"; readonly length: N };\n /** `str` - fixed-length text; longer than `length` throws on write. */\n readonly char: <N extends number>(length: N) => { readonly type: \"char\"; readonly length: N };\n /**\n * `num` - exact decimal of `precision` digits, `scale` (default 0) after the point.\n *\n * A value past either throws on write.\n */\n readonly numeric: (precision: number, scale?: number) => { readonly type: \"numeric\"; readonly precision: number; readonly scale: number };\n /** `num` - exact decimal, as `numeric`. */\n readonly decimal: (precision: number, scale?: number) => { readonly type: \"decimal\"; readonly precision: number; readonly scale: number };\n}\n\n/**\n * Column datatypes, passed to a field helper - `str(sql.varchar(255))`, `date(sql.date)`.\n *\n * Each fits only the helpers named on it; elsewhere it is a type error.\n */\nconst sql: Datatypes = {\n now,\n text: { type: \"text\" },\n uuid: { type: \"uuid\" },\n integer: { type: \"integer\" },\n smallint: { type: \"smallint\" },\n bigint: { type: \"bigint\" },\n real: { type: \"real\" },\n double: { type: \"double\" },\n timestamp: { type: \"timestamp\" },\n date: { type: \"date\" },\n time: { type: \"time\" },\n varchar: <N extends number>(length: N) => ({ type: \"varchar\", length }) as const,\n char: <N extends number>(length: N) => ({ type: \"char\", length }) as const,\n numeric: (precision: number, scale = 0) => ({ type: \"numeric\", precision, scale }) as const,\n decimal: (precision: number, scale = 0) => ({ type: \"decimal\", precision, scale }) as const\n};\n\nexport { sql };\n"],"mappings":";;;;;;;;AA4CA,MAAM,MAAiB;CACrB;CACA,MAAM,EAAE,MAAM,QAAQ;CACtB,MAAM,EAAE,MAAM,QAAQ;CACtB,SAAS,EAAE,MAAM,WAAW;CAC5B,UAAU,EAAE,MAAM,YAAY;CAC9B,QAAQ,EAAE,MAAM,UAAU;CAC1B,MAAM,EAAE,MAAM,QAAQ;CACtB,QAAQ,EAAE,MAAM,UAAU;CAC1B,WAAW,EAAE,MAAM,aAAa;CAChC,MAAM,EAAE,MAAM,QAAQ;CACtB,MAAM,EAAE,MAAM,QAAQ;CACtB,UAA4B,YAAe;EAAE,MAAM;EAAW;EAAQ;CACtE,OAAyB,YAAe;EAAE,MAAM;EAAQ;EAAQ;CAChE,UAAU,WAAmB,QAAQ,OAAO;EAAE,MAAM;EAAW;EAAW;EAAO;CACjF,UAAU,WAAmB,QAAQ,OAAO;EAAE,MAAM;EAAW;EAAW;EAAO;CAClF"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@expressive/sql",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.9.1",
|
|
4
4
|
"description": "Expressive ORM on SQL: entities, Query and an embedded SQLite store from one import.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"orm",
|
|
@@ -59,7 +59,7 @@
|
|
|
59
59
|
"test": "bun run typecheck && bun run coverage"
|
|
60
60
|
},
|
|
61
61
|
"dependencies": {
|
|
62
|
-
"@expressive/orm": "^0.
|
|
62
|
+
"@expressive/orm": "^0.19.0",
|
|
63
63
|
"sql-formatter": "^10.7.2"
|
|
64
64
|
},
|
|
65
65
|
"devDependencies": {
|
|
@@ -5,13 +5,13 @@ description: Expressive ORM on SQL (@expressive/sql) - SQLiteConnection with a b
|
|
|
5
5
|
|
|
6
6
|
# @expressive/sql
|
|
7
7
|
|
|
8
|
-
Expressive ORM on SQL, with embedded SQLite. Re-exports `@expressive/orm` - entities, fields, relations, `Query
|
|
8
|
+
Expressive ORM on SQL, with embedded SQLite. Re-exports `@expressive/orm` - entities, fields, relations, `Query`, transactions and `Memory` are in `expressive-orm`. Apps import everything from `@expressive/sql`.
|
|
9
9
|
|
|
10
10
|
```bash
|
|
11
11
|
npm install @expressive/sql @expressive/mvc
|
|
12
12
|
```
|
|
13
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`)
|
|
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`).
|
|
15
15
|
|
|
16
16
|
## Connect
|
|
17
17
|
|
|
@@ -27,13 +27,11 @@ const db = await SQLiteConnection.new([User], "app.db"); // omit the filename
|
|
|
27
27
|
await db.close();
|
|
28
28
|
```
|
|
29
29
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
`sync` covers the classes passed to `new`. `static connection = db` binds another class without syncing it. `db.schema` is the DDL.
|
|
30
|
+
A filename or in-memory connection enforces foreign keys. `sync` covers the classes passed to `new` - list every class; an unlisted one has no connection. `db.schema` is the DDL. A failed statement throws `Error running SQL: <message>` followed by the SQL.
|
|
33
31
|
|
|
34
32
|
### Engine
|
|
35
33
|
|
|
36
|
-
In place of the filename, pass an `Engine` for a SQLite the built-in loader can't open
|
|
34
|
+
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
35
|
|
|
38
36
|
```ts
|
|
39
37
|
import type { Engine } from '@expressive/sql';
|
|
@@ -49,7 +47,9 @@ const engine: Engine = {
|
|
|
49
47
|
const db = await SQLiteConnection.new([User], engine);
|
|
50
48
|
```
|
|
51
49
|
|
|
52
|
-
A given engine is used as is - turn on foreign keys yourself where the host doesn't - and `close()` leaves it open.
|
|
50
|
+
A given engine, binding or client is used as is - turn on foreign keys yourself where the host doesn't - and `close()` leaves it open.
|
|
51
|
+
|
|
52
|
+
On React Native (Metro, iOS and Android) the built-in loader is swapped out: a filename or libSQL address rejects with `... does not load under React Native. Pass an Engine instead.` Expo web does not bundle `@expressive/sql`. `transaction` throws there - no `AsyncLocalStorage`.
|
|
53
53
|
|
|
54
54
|
Two optional members, for hosts without `BEGIN` and `COMMIT` on one connection:
|
|
55
55
|
|
|
@@ -58,7 +58,7 @@ Two optional members, for hosts without `BEGIN` and `COMMIT` on one connection:
|
|
|
58
58
|
|
|
59
59
|
### Hosts
|
|
60
60
|
|
|
61
|
-
In place of the filename, `new` also takes a D1 binding, a libSQL `Client` or a libSQL address, told apart by shape.
|
|
61
|
+
In place of the filename, `new` also takes a D1 binding, a libSQL `Client` or a libSQL address, told apart by shape.
|
|
62
62
|
|
|
63
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
64
|
|
|
@@ -78,7 +78,7 @@ function open(DB: D1Database){
|
|
|
78
78
|
export default {
|
|
79
79
|
async fetch(request: Request, env: { DB: D1Database }) {
|
|
80
80
|
await (ready ??= open(env.DB));
|
|
81
|
-
return Response.json(await User.
|
|
81
|
+
return Response.json(await User.query());
|
|
82
82
|
}
|
|
83
83
|
};
|
|
84
84
|
```
|
|
@@ -86,7 +86,7 @@ export default {
|
|
|
86
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
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
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
|
|
89
|
+
- A `migrate` rebuild refuses dangling rows (`foreign_key_check`) even where foreign keys are off.
|
|
90
90
|
|
|
91
91
|
## Sync
|
|
92
92
|
|
|
@@ -98,6 +98,7 @@ Awaiting a connection runs `sync`:
|
|
|
98
98
|
- `static schema` is reported - SQLite has none.
|
|
99
99
|
- A relation column missing while `<table>_id` exists is reported, not added - set `{ column: "<table>_id" }` to keep the old one.
|
|
100
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
|
+
- `sync` runs once - after the await it throws `Connection is already active.` To force a rebuild, call `sync(true, true)` on the connection instead of awaiting it, or run `expressive sql sync --force`.
|
|
101
102
|
|
|
102
103
|
### Command line
|
|
103
104
|
|
|
@@ -107,20 +108,20 @@ expressive sql sync src/db.ts # create missing tables, columns and index
|
|
|
107
108
|
expressive sql sync --force src/db.ts # also rebuild drifted columns
|
|
108
109
|
```
|
|
109
110
|
|
|
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
|
|
111
|
+
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 awaited while it loads. The entry must not query at load - the tables may not exist yet. A TypeScript entry needs Bun (`bunx --bun expressive ...`) or Node 22.18+.
|
|
111
112
|
|
|
112
113
|
## Datatypes
|
|
113
114
|
|
|
114
|
-
Datatypes are
|
|
115
|
+
Datatypes are orm's (`expressive-orm/SKILL.md#entities`); `sql.*` is shorthand for the declaration: `str(sql.varchar(40))` is `str({ type: "varchar", length: 40 })`. SQLite stores:
|
|
115
116
|
|
|
116
|
-
| Helper |
|
|
117
|
-
|
|
118
|
-
| `str` |
|
|
119
|
-
| `num` |
|
|
120
|
-
| `bool` |
|
|
121
|
-
| `date` |
|
|
122
|
-
| `json` |
|
|
123
|
-
| `one` |
|
|
117
|
+
| Helper | SQLite |
|
|
118
|
+
|---|---|
|
|
119
|
+
| `str` | TEXT |
|
|
120
|
+
| `num` | INTEGER; `real`, `double` REAL; `numeric`, `decimal` NUMERIC |
|
|
121
|
+
| `bool` | INTEGER, 1 or 0 |
|
|
122
|
+
| `date` | TEXT - ISO 8601 UTC to the ms; `date` the local day `YYYY-MM-DD`; `time` UTC `HH:MM:SS` |
|
|
123
|
+
| `json` | TEXT |
|
|
124
|
+
| `one` | the related key's |
|
|
124
125
|
|
|
125
126
|
```ts
|
|
126
127
|
import { Type, date, key, num, sql, str } from '@expressive/sql';
|
|
@@ -135,13 +136,10 @@ class Product extends Type {
|
|
|
135
136
|
```
|
|
136
137
|
|
|
137
138
|
- `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
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.
|
|
141
|
-
-
|
|
142
|
-
- `
|
|
143
|
-
- A `date` type is a calendar day: a Date gives its local day, `"YYYY-MM-DD"` is that day, and it reads back as local midnight. It crosses the floor and is stored as `YYYY-MM-DD`, so zones never shift it. `sql.now` on it is the database's UTC day. A `time` is a UTC time of day, crossing as a Date on 1970-01-01 UTC.
|
|
144
|
-
- Storage-only types are gone: store epoch time as `num(sql.bigint)`, yes/no text as `str`.
|
|
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.
|
|
141
|
+
- The SQL floor checks values again before storing, so rows forwarded from a client meet the same rules.
|
|
142
|
+
- A `date` type is a calendar day, read back as local midnight and stored `YYYY-MM-DD`, so zones never shift it; `sql.now` on it is the UTC day.
|
|
145
143
|
|
|
146
144
|
`codecs` maps each base helper to how SQL stores it (`Connection.Codec`). A dialect extends it - `new Map([...codecs, [date, myDateCodec]])` - and returns it from a protected `codecs` getter.
|
|
147
145
|
|