@kerf-js/db 0.0.0-stage → 0.1.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.
@@ -0,0 +1,80 @@
1
+ // Prisma: `withKerf(client, dialect)` returns the same client with the handle the server
2
+ // migrates and Q011 reads. Migrations are `prisma/migrations`, applied here because `prisma migrate deploy` isn't in a
3
+ // production bundle. Interactive transactions keep the lock and the statements on one connection. It stays Prisma's own
4
+ // client, so kerf can't hold a statement: the server runs the gate per request instead, and a failed run doesn't fail it.
5
+
6
+ import { gate, register, touch, type DbHandle, type Migration } from '@kerf-js/start/db/core'
7
+ import { runtime } from '@kerf-js/start/data'
8
+
9
+ type Dialect = DbHandle['dialect']
10
+ interface Tx {
11
+ $executeRawUnsafe(sql: string, ...values: unknown[]): Promise<number>
12
+ $queryRawUnsafe<T>(sql: string, ...values: unknown[]): Promise<T>
13
+ }
14
+ interface Client extends Tx {
15
+ $on?(event: 'query', fn: (e: { query: string }) => void): void
16
+ $transaction<T>(
17
+ fn: (tx: Tx) => Promise<T>,
18
+ options: { maxWait: number; timeout: number },
19
+ ): Promise<T>
20
+ }
21
+
22
+ const LOCK = 7_301_988
23
+ const statements = (sql: string) =>
24
+ sql
25
+ .split(/;[ \t]*(?:\r?\n|$)/)
26
+ .map((s) => s.replace(/^(\s*--.*\n)+/, '').trim())
27
+ .filter(Boolean)
28
+
29
+ /** The same client, with `$kerf`: the handle the server migrates and Q011 reads. */
30
+ export function withKerf<C extends object>(
31
+ client: C,
32
+ dialect: Dialect,
33
+ { migrate = true }: { migrate?: boolean | undefined } = {},
34
+ ): C & { $kerf: DbHandle } {
35
+ const c = client as unknown as Client
36
+ const handle: DbHandle = {
37
+ dialect,
38
+ exempt: new Set(),
39
+ migrate: (list: Migration[]) =>
40
+ c.$transaction(
41
+ async (tx) => {
42
+ if (dialect === 'postgresql')
43
+ await tx.$queryRawUnsafe(`select pg_advisory_xact_lock(${LOCK})::text`)
44
+ if (dialect === 'mysql') {
45
+ const got = await tx.$queryRawUnsafe<{ got: unknown }[]>(
46
+ `select get_lock('kerf_migrations', 60) as got`,
47
+ )
48
+ if (Number(got[0]?.got) !== 1)
49
+ throw new Error('another instance held the migration lock for 60s')
50
+ }
51
+ try {
52
+ await tx.$executeRawUnsafe(
53
+ 'create table if not exists __kerf_migrations (tag varchar(255) primary key)',
54
+ )
55
+ const done = new Set(
56
+ (
57
+ await tx.$queryRawUnsafe<{ tag: string }[]>('select tag from __kerf_migrations')
58
+ ).map((r) => r.tag),
59
+ )
60
+ for (const m of list) {
61
+ if (done.has(m.tag)) continue
62
+ for (const s of statements(m.sql)) await tx.$executeRawUnsafe(s)
63
+ await tx.$executeRawUnsafe(
64
+ `insert into __kerf_migrations (tag) values (${dialect === 'postgresql' ? '$1' : '?'})`,
65
+ m.tag,
66
+ )
67
+ }
68
+ } finally {
69
+ // MySQL's lock belongs to the connection, not the transaction: a failed run would keep it in the pool.
70
+ if (dialect === 'mysql')
71
+ await tx.$queryRawUnsafe(`select release_lock('kerf_migrations')`).catch(() => {})
72
+ }
73
+ },
74
+ { maxWait: 60_000, timeout: 120_000 },
75
+ ),
76
+ }
77
+ c.$on?.('query', (e) => touch(handle, e.query))
78
+ ;(runtime.dbs ??= new Set()).add(gate(handle, migrate))
79
+ return register(client, handle)
80
+ }
package/src/prisma.ts ADDED
@@ -0,0 +1,136 @@
1
+ // A list source over a Prisma model delegate: `prismaSource(ctx.db.task, { columns })`. It only reads what a delegate
2
+ // has, so it needs nothing from `@prisma/client` and works with any generated client.
3
+
4
+ import {
5
+ pageOf,
6
+ plan,
7
+ rowOf,
8
+ storedId,
9
+ written,
10
+ type DbAdapter,
11
+ type ListParams,
12
+ type ListSource,
13
+ type SourceSpec,
14
+ } from '@kerf-js/start/list'
15
+
16
+ /** What a generated client's model has, whatever its schema. */
17
+ export interface PrismaDelegate {
18
+ findMany(args: unknown): Promise<object[]>
19
+ findUnique(args: unknown): Promise<object | null>
20
+ count(args: unknown): Promise<number>
21
+ create(args: unknown): Promise<object>
22
+ update(args: unknown): Promise<object>
23
+ delete(args: unknown): Promise<object>
24
+ }
25
+
26
+ /** A source's allowlist, and how `search` compares. */
27
+ export interface PrismaSpec extends SourceSpec {
28
+ /** `mode: 'insensitive'` on `contains`, which Postgres and Mongo have. SQLite and MySQL compare without case already. Default true. */
29
+ insensitive?: boolean
30
+ }
31
+
32
+ const MISSING = 'P2025'
33
+
34
+ type PrismaList<Row> = {
35
+ model: PrismaDelegate
36
+ spec: PrismaSpec
37
+ select: Record<string, boolean>
38
+ idColumn: string
39
+ reading: (row: object) => Row
40
+ escaped: boolean
41
+ }
42
+
43
+ async function listRows<Row>(p: ListParams, context: PrismaList<Row>) {
44
+ const { model, spec, select, idColumn, reading, escaped } = context
45
+ const q = plan(spec, p)
46
+ const and: object[] = q.where.map((w) => {
47
+ const some = w.values.filter((v) => v !== null)
48
+ return {
49
+ OR: [
50
+ ...(some.length ? [{ [w.column]: { in: some } }] : []),
51
+ ...(w.values.includes(null) ? [{ [w.column]: null }] : []),
52
+ ],
53
+ }
54
+ })
55
+ if (q.search) {
56
+ const term = q.search.text.replace(/[\\%_]/g, '\\$&')
57
+ and.push({
58
+ OR: q.search.columns.map((c) => ({
59
+ [c]: { contains: term, ...(escaped ? { mode: 'insensitive' } : {}) },
60
+ })),
61
+ })
62
+ }
63
+ const where = { AND: and }
64
+ const dir = q.sort?.dir === 'desc' ? 'desc' : 'asc',
65
+ cmp = dir === 'desc' ? 'lt' : 'gt'
66
+ const keyset = p.after
67
+ ? q.sort
68
+ ? {
69
+ OR: [
70
+ { [q.sort.column]: { [cmp]: p.after[0] } },
71
+ { [q.sort.column]: p.after[0], [idColumn]: { [cmp]: p.after[1] } },
72
+ ],
73
+ }
74
+ : { [idColumn]: { gt: p.after[1] } }
75
+ : undefined
76
+ const orderBy = q.sort ? [{ [q.sort.column]: dir }, { [idColumn]: dir }] : [{ [idColumn]: 'asc' }]
77
+ const cursor = p.mode === 'cursor'
78
+ const rows = (
79
+ await model.findMany({
80
+ select,
81
+ where: keyset ? { AND: [where, keyset] } : where,
82
+ orderBy,
83
+ take: cursor ? p.limit + 1 : p.limit,
84
+ skip: p.offset,
85
+ })
86
+ ).map(reading)
87
+ return pageOf(
88
+ rows,
89
+ p,
90
+ { sort: q.sort?.field, id: q.id.field },
91
+ cursor ? undefined : await model.count({ where }),
92
+ )
93
+ }
94
+
95
+ /** A `ListSource` over one Prisma model. */
96
+ export function prismaSource<Row = Record<string, unknown>>(
97
+ model: PrismaDelegate,
98
+ spec: PrismaSpec,
99
+ ): ListSource<Row> {
100
+ const select = Object.fromEntries(Object.values(spec.columns).map((c) => [c, true]))
101
+ const reading = rowOf<Row>(spec)
102
+ const idColumn = storedId(spec)
103
+ const missing = (e: unknown) => {
104
+ if ((e as { code?: string } | null)?.code !== MISSING) throw e
105
+ return null
106
+ }
107
+ // Prisma leaves `%` and `_` as wildcards in `contains`, so a term with either is checked again here.
108
+ const escaped = spec.insensitive !== false
109
+ return {
110
+ limits: { search: 'cased' },
111
+ list(p: ListParams) {
112
+ return listRows(p, { model, spec, select, idColumn, reading, escaped })
113
+ },
114
+ get: async (id) => {
115
+ const r = await model.findUnique({ where: { [idColumn]: id }, select })
116
+ return r ? reading(r) : null
117
+ },
118
+ create: async (data) =>
119
+ reading(await model.create({ data: written(spec, data, true), select })),
120
+ update: (id, patch) => {
121
+ const data = written(spec, patch)
122
+ return model.update({ where: { [idColumn]: id }, data, select }).then(reading, missing)
123
+ },
124
+ remove: (id) =>
125
+ model.delete({ where: { [idColumn]: id }, select: { [idColumn]: true } }).then(
126
+ () => true,
127
+ (e) => missing(e) ?? false,
128
+ ),
129
+ }
130
+ }
131
+
132
+ /** `db.adapter@1` over a Prisma model. */
133
+ export const adapter: DbAdapter<PrismaDelegate> = {
134
+ name: 'prisma',
135
+ source: (t, spec) => prismaSource(t, spec),
136
+ }
package/src/sql.ts ADDED
@@ -0,0 +1,216 @@
1
+ // A list source from bound SQL: `columns` is required, identifiers come only from it, and every value
2
+ // is a parameter. `target` is anything with `query(text, params)`: `ctx.db` from `@kerf-js/db/plugin-native`, or a driver.
3
+
4
+ import {
5
+ likeOf,
6
+ pageOf,
7
+ plan,
8
+ rowOf,
9
+ storedId,
10
+ written,
11
+ type DbAdapter,
12
+ type ListParams,
13
+ type ListSource,
14
+ type SourceSpec,
15
+ } from '@kerf-js/start/list'
16
+ import { StartError } from '@kerf-js/start/data'
17
+
18
+ /** Whatever runs a bound statement, and says which dialect it speaks. */
19
+ export interface SqlTarget {
20
+ query(text: string, params: unknown[]): Promise<Record<string, unknown>[]>
21
+ dialect?: 'postgresql' | 'sqlite' | 'mysql'
22
+ $kerf?: { dialect: 'postgresql' | 'sqlite' | 'mysql' }
23
+ }
24
+
25
+ /** A source's allowlist, and the table it covers. */
26
+ export interface SqlSpec extends SourceSpec {
27
+ table: string
28
+ }
29
+
30
+ const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/
31
+
32
+ function ident(dialect: string) {
33
+ const q = dialect === 'mysql' ? '`' : '"'
34
+ return (name: string) => {
35
+ if (!IDENT.test(name))
36
+ throw new StartError(
37
+ 'Q002',
38
+ `\`${name}\` is not a plain identifier, so it can't go in SQL`,
39
+ 'use a column name',
40
+ )
41
+ return `${q}${name}${q}`
42
+ }
43
+ }
44
+
45
+ function listSql<Row>({
46
+ target,
47
+ spec,
48
+ q,
49
+ bind,
50
+ read,
51
+ table,
52
+ select,
53
+ idColumn,
54
+ }: {
55
+ target: SqlTarget
56
+ spec: SqlSpec
57
+ q: (name: string) => string
58
+ bind: (params: unknown[]) => (value: unknown) => string
59
+ read: (text: string, params: unknown[]) => Promise<Row[]>
60
+ table: string
61
+ select: string
62
+ idColumn: string
63
+ }): ListSource<Row>['list'] {
64
+ return async function list(p: ListParams) {
65
+ const qp = plan(spec, p)
66
+ const params: unknown[] = []
67
+ const put = bind(params)
68
+ const parts = qp.where.map((w) => {
69
+ const some = w.values.filter((v) => v !== null)
70
+ const hit =
71
+ some.length === 1
72
+ ? `${q(w.column)} = ${put(some[0])}`
73
+ : some.length
74
+ ? `${q(w.column)} in (${some.map(put).join(', ')})`
75
+ : ''
76
+ return w.values.includes(null) ? `(${hit ? `${hit} or ` : ''}${q(w.column)} is null)` : hit
77
+ })
78
+ if (qp.search) {
79
+ const text = likeOf(qp.search.text)
80
+ parts.push(
81
+ `(${qp.search.columns.map((c) => `lower(${q(c)}) like ${put(text)} escape '!'`).join(' or ')})`,
82
+ )
83
+ }
84
+ const filtered = [...parts],
85
+ mark = params.length // what the count binds: the keyset isn't part of it
86
+ const cmp = qp.sort?.dir === 'desc' ? '<' : '>'
87
+ if (p.after) {
88
+ const [value, id] = p.after
89
+ const col = qp.sort && q(qp.sort.column)
90
+ parts.push(
91
+ col
92
+ ? `(${col} ${cmp} ${put(value)} or (${col} = ${put(value)} and ${idColumn} ${cmp} ${put(id)}))`
93
+ : `${idColumn} > ${put(id)}`,
94
+ )
95
+ }
96
+ const where = (conditions: string[]) =>
97
+ conditions.length ? ` where ${conditions.join(' and ')}` : ''
98
+ const dir = qp.sort?.dir === 'desc' ? 'desc' : 'asc'
99
+ const order = qp.sort ? `${q(qp.sort.column)} ${dir}, ${idColumn} ${dir}` : `${idColumn} asc`
100
+ const cursor = p.mode === 'cursor'
101
+ const counted = params.slice(0, mark)
102
+ const rows = await read(
103
+ `select ${select} from ${table}${where(parts)} order by ${order} limit ${Math.trunc(cursor ? p.limit + 1 : p.limit)} offset ${Math.trunc(p.offset)}`,
104
+ params,
105
+ )
106
+ const total = cursor
107
+ ? undefined
108
+ : Number(
109
+ (await target.query(`select count(*) as n from ${table}${where(filtered)}`, counted))[0]!
110
+ .n,
111
+ )
112
+ return pageOf(rows, p, { sort: qp.sort?.field, id: qp.id.field }, total)
113
+ }
114
+ }
115
+
116
+ /** A `ListSource` over one table, as bound SQL. */
117
+ export function sqlSource<Row = Record<string, unknown>>(
118
+ target: SqlTarget,
119
+ spec: SqlSpec,
120
+ ): ListSource<Row> {
121
+ const dialect = target.dialect ?? target.$kerf?.dialect ?? 'postgresql'
122
+ const q = ident(dialect)
123
+ for (const c of [spec.table, ...Object.values(spec.columns)]) q(c)
124
+ const table = q(spec.table)
125
+ const select = Object.values(spec.columns).map(q).join(', ')
126
+ const reading = rowOf<Row>(spec)
127
+ const idColumn = q(storedId(spec))
128
+ const bind = (params: unknown[]) => (v: unknown) => {
129
+ params.push(v)
130
+ return dialect === 'postgresql' ? `$${params.length}` : '?'
131
+ }
132
+ const read = async (text: string, params: unknown[]) =>
133
+ (await target.query(text, params)).map(reading)
134
+ const byId = (id: unknown) => {
135
+ const params: unknown[] = []
136
+ return read(
137
+ `select ${select} from ${table} where ${idColumn} = ${bind(params)(id)}`,
138
+ params,
139
+ ).then((r) => r[0] ?? null)
140
+ }
141
+ return {
142
+ list: listSql({ target, spec, q, bind, read, table, select, idColumn }),
143
+ get: byId,
144
+ async create(data) {
145
+ const row = written(spec, data, true)
146
+ const id = data[spec.id ?? 'id']
147
+ if (id === undefined)
148
+ throw new StartError(
149
+ 'Q002',
150
+ "`create` needs the id: a generated one can't be read back on every dialect",
151
+ 'generate it before the insert',
152
+ )
153
+ const keys = Object.keys(row),
154
+ params: unknown[] = [],
155
+ put = bind(params)
156
+ await target.query(
157
+ `insert into ${table} (${keys.map(q).join(', ')}) values (${keys.map((k) => put(row[k])).join(', ')})`,
158
+ params,
159
+ )
160
+ return (await byId(id))!
161
+ },
162
+ async update(id, patch) {
163
+ const row = written(spec, patch),
164
+ params: unknown[] = [],
165
+ put = bind(params)
166
+ const sets = Object.keys(row).map((k) => `${q(k)} = ${put(row[k])}`)
167
+ if (!(await byId(id))) return null
168
+ if (sets.length)
169
+ await target.query(
170
+ `update ${table} set ${sets.join(', ')} where ${idColumn} = ${put(id)}`,
171
+ params,
172
+ )
173
+ return byId(id)
174
+ },
175
+ async remove(id) {
176
+ if (!(await byId(id))) return false
177
+ const params: unknown[] = []
178
+ await target.query(`delete from ${table} where ${idColumn} = ${bind(params)(id)}`, params)
179
+ return true
180
+ },
181
+ }
182
+ }
183
+
184
+ /** `db.adapter@1` over bound SQL. */
185
+ export const adapter: DbAdapter<SqlTarget> = {
186
+ name: 'sql',
187
+ source: (t, spec) => sqlSource(t, spec as SqlSpec),
188
+ }
189
+
190
+ /**
191
+ * A trigger so writes from anywhere (cron, psql, another service) reach `.live` queries, on the postgres bus: tags, never
192
+ * rows. Run the text once in a migration.
193
+ */
194
+ export function postgresTrigger({
195
+ table,
196
+ id = 'id',
197
+ tag = table,
198
+ }: {
199
+ table: string
200
+ id?: string
201
+ tag?: string
202
+ }): string {
203
+ const q = ident('postgresql')
204
+ if (!/^[\w:-]+$/.test(tag)) throw new StartError('Q002', `\`${tag}\` can't be a tag in a trigger`)
205
+ const fn = `kerf_poke_${table}`
206
+ return `create or replace function ${q(fn)}() returns trigger language plpgsql as $$
207
+ declare row_id text;
208
+ begin
209
+ if tg_op = 'DELETE' then row_id := old.${q(id)}::text; else row_id := new.${q(id)}::text; end if;
210
+ perform pg_notify('kerf_bus', '=kerf:poke' || chr(10) || json_build_object('t', json_build_array('${tag}', '${tag}:' || row_id))::text);
211
+ return null;
212
+ end $$;
213
+ drop trigger if exists ${q(fn)} on ${q(table)};
214
+ create trigger ${q(fn)} after insert or update or delete on ${q(table)} for each row execute function ${q(fn)}();
215
+ `
216
+ }