@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 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.find({ age: greaterThan(17) });
29
+ const adults = await User.query({ age: greaterThan(17) });
30
30
 
31
31
  const titles = await Query(where => {
32
32
  const post = where(Post);
@@ -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.ms)`.
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.ms)`.
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
  */
@@ -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.ms)`.\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"}
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.8.3",
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.17.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` and transactions are in `expressive-orm`. Apps import everything from `@expressive/sql`; driver seams come from `@expressive/orm/driver`.
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`), which re-exports this package.
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
- 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.
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, such as on React Native - any object with these, each async:
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. A given binding or client is used as is; `close()` leaves it open.
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.find({}));
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, and leaves them on.
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 created. A TypeScript entry needs Bun (`bunx --bun expressive ...`) or Node 22.18+.
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 portable - orm declares them, and each connection maps them to its storage. `sql.*` is shorthand for the declaration: `str(sql.varchar(40))` is `str({ type: "varchar", length: 40 })`. A schema module importing only `@expressive/orm` writes the object form and binds here unchanged.
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 | `sql.*` | SQLite |
117
- |---|---|---|
118
- | `str` | `text` (default), `varchar(n)`, `char(n)`, `uuid` | TEXT |
119
- | `num` | `integer` (default), `smallint`, `bigint`, `real`, `double`, `numeric(p, s)`, `decimal(p, s)` | INTEGER, REAL, NUMERIC |
120
- | `bool` | - (boolean) | INTEGER, 1 or 0 |
121
- | `date` | `timestamp` (default), `date`, `time` | TEXT - ISO 8601 UTC to the ms; `date` as the local day `YYYY-MM-DD`; `time` as UTC `HH:MM:SS` |
122
- | `json` | - | TEXT |
123
- | `one` | - (the related key's) | the key's |
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. `"NOW"` is a deprecated alias.
141
- - Writes are checked by the field on every connection - `varchar` and `char` length, integer ranges, decimal precision and scale. The SQL floor checks again before storing, so rows forwarded from a client meet the same rules.
142
- - `Connection.new` throws for a datatype the connection can't store - `SQLiteConnection can't store json type 'blob' (Doc.blob).`
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