@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,226 @@
1
+ // A list source over a DynamoDB table, through a `DynamoDBDocumentClient`. DynamoDB has no offset and sorts only inside a
2
+ // partition, so this is cursor mode only: a `Scan` by default, and a `Query` when `partition` and `sortKey` name an index.
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
+ import { StartError } from '@kerf-js/start/data'
16
+ import { driver } from './driver'
17
+
18
+ const { DeleteCommand, GetCommand, PutCommand, QueryCommand, ScanCommand, UpdateCommand } =
19
+ await driver(
20
+ '@kerf-js/db/dynamodb',
21
+ '@aws-sdk/lib-dynamodb',
22
+ () => import('@aws-sdk/lib-dynamodb'),
23
+ )
24
+
25
+ type Item = Record<string, unknown>
26
+
27
+ /** What a command answers, as far as a source reads it. */
28
+ export interface DynamoReply {
29
+ Item?: Item | undefined
30
+ Items?: Item[] | undefined
31
+ Attributes?: Item | undefined
32
+ LastEvaluatedKey?: Item | undefined
33
+ }
34
+
35
+ /** A `DynamoDBDocumentClient`, or anything else that sends these commands, and the table to send them to. */
36
+ export interface DynamoTarget {
37
+ client: { send(command: object): Promise<DynamoReply> }
38
+ table: string
39
+ }
40
+
41
+ /** A source's allowlist, and the index that lets a list sort. */
42
+ export interface DynamoSpec extends SourceSpec {
43
+ /** With `sortKey`: list one partition through `index`, sorted. */
44
+ partition?: { column: string; value: unknown }
45
+ /** The public name of the index's sort key: the one thing that can be sorted on. */
46
+ sortKey?: string
47
+ index?: string
48
+ }
49
+
50
+ const CONDITION = 'ConditionalCheckFailedException'
51
+ const PAGE = 1 << 12
52
+
53
+ type DynamoList<Row> = {
54
+ client: DynamoTarget['client']
55
+ table: string
56
+ spec: DynamoSpec
57
+ idColumn: string
58
+ sortColumn: string | undefined
59
+ projection: string
60
+ names: Record<string, string>
61
+ reading: (row: object) => Row
62
+ idField: string
63
+ }
64
+
65
+ async function listRows<Row>(p: ListParams, context: DynamoList<Row>) {
66
+ const { client, table, spec, idColumn, sortColumn, projection, names, reading, idField } = context
67
+ if (p.mode === 'page')
68
+ throw new StartError('Q002', 'DynamoDB has no offset', "ask for `mode: 'cursor'`")
69
+ const q = plan(spec, p)
70
+ if (q.sort && q.sort.field !== spec.sortKey)
71
+ throw new StartError(
72
+ 'Q002',
73
+ `DynamoDB can sort only on the index's key, not \`${q.sort.field}\``,
74
+ 'set `sortKey`',
75
+ )
76
+ const values: Record<string, unknown> = {},
77
+ ExpressionAttributeNames: Record<string, string> = { ...names }
78
+ let n = 0
79
+ const value = (v: unknown) => {
80
+ const k = `:v${n++}`
81
+ values[k] = v
82
+ return k
83
+ }
84
+ const name = (c: string) => {
85
+ const k = `#n${n++}`
86
+ ExpressionAttributeNames[k] = c
87
+ return k
88
+ }
89
+ const parts = q.where.map((w) => {
90
+ const col = name(w.column)
91
+ return `(${w.values.map((v) => (v === null ? `attribute_not_exists(${col})` : `${col} = ${value(v)}`)).join(' or ')})`
92
+ })
93
+ if (q.search) {
94
+ const v = value(q.search.text)
95
+ parts.push(`(${q.search.columns.map((c) => `contains(${name(c)}, ${v})`).join(' or ')})`)
96
+ }
97
+ const query = spec.partition && sortColumn
98
+ const KeyConditionExpression = query
99
+ ? `${name(spec.partition!.column)} = ${value(spec.partition!.value)}`
100
+ : undefined
101
+ const start = p.after
102
+ ? {
103
+ [idColumn]: p.after[1],
104
+ ...(query
105
+ ? { [spec.partition!.column]: spec.partition!.value, [sortColumn]: p.after[0] }
106
+ : {}),
107
+ }
108
+ : undefined
109
+ const rows: Item[] = []
110
+ let ExclusiveStartKey: Item | undefined = start
111
+ // `Limit` counts what's read before the filter, so a page can take several trips.
112
+ do {
113
+ const input = {
114
+ TableName: table,
115
+ ProjectionExpression: projection,
116
+ ExpressionAttributeNames,
117
+ ...(Object.keys(values).length ? { ExpressionAttributeValues: values } : {}),
118
+ ...(parts.length ? { FilterExpression: parts.join(' and ') } : {}),
119
+ ...(ExclusiveStartKey ? { ExclusiveStartKey } : {}),
120
+ Limit: PAGE,
121
+ }
122
+ const r: DynamoReply = await client.send(
123
+ query
124
+ ? new QueryCommand({
125
+ ...input,
126
+ IndexName: spec.index,
127
+ KeyConditionExpression,
128
+ ScanIndexForward: q.sort?.dir !== 'desc',
129
+ })
130
+ : new ScanCommand(input),
131
+ )
132
+ rows.push(...(r.Items ?? []))
133
+ ExclusiveStartKey = r.LastEvaluatedKey
134
+ } while (ExclusiveStartKey && rows.length <= p.limit)
135
+ return pageOf(rows.slice(0, p.limit + 1).map(reading), p, {
136
+ sort: q.sort?.field ?? spec.sortKey,
137
+ id: idField,
138
+ })
139
+ }
140
+
141
+ /** A `ListSource` over one table, in cursor mode. */
142
+ export function dynamoSource<Row = Record<string, unknown>>(
143
+ { client, table }: DynamoTarget,
144
+ spec: DynamoSpec,
145
+ ): ListSource<Row> {
146
+ const reading = rowOf<Row>(spec)
147
+ const idField = spec.id ?? 'id',
148
+ idColumn = storedId(spec)
149
+ const key = (id: unknown) => ({ [idColumn]: id })
150
+ const sortColumn = spec.sortKey && spec.columns[spec.sortKey]
151
+ const stored = Object.values(spec.columns)
152
+ const projection = stored.map((_, i) => `#c${i}`).join(', ')
153
+ const names = Object.fromEntries(stored.map((c, i) => [`#c${i}`, c]))
154
+ const byId = async (id: unknown) => {
155
+ const r = await client.send(
156
+ new GetCommand({ TableName: table, Key: key(id), ConsistentRead: true }),
157
+ )
158
+ return r.Item ? reading(r.Item) : null
159
+ }
160
+ return {
161
+ limits: { page: false, search: 'cased', sort: spec.sortKey ? [spec.sortKey] : [] },
162
+ list(p: ListParams) {
163
+ return listRows(p, {
164
+ client,
165
+ table,
166
+ spec,
167
+ idColumn,
168
+ sortColumn,
169
+ projection,
170
+ names,
171
+ reading,
172
+ idField,
173
+ })
174
+ },
175
+ get: byId,
176
+ async create(data) {
177
+ const Item = {
178
+ ...written(spec, data, true),
179
+ ...(spec.partition ? { [spec.partition.column]: spec.partition.value } : {}),
180
+ }
181
+ await client.send(new PutCommand({ TableName: table, Item }))
182
+ return reading(Item)
183
+ },
184
+ async update(id, patch) {
185
+ const row = written(spec, patch)
186
+ const keys = Object.keys(row)
187
+ if (!keys.length) return byId(id)
188
+ const ExpressionAttributeNames: Record<string, string> = { '#id': idColumn },
189
+ ExpressionAttributeValues: Record<string, unknown> = {}
190
+ keys.forEach((k, i) => {
191
+ ExpressionAttributeNames[`#k${i}`] = k
192
+ ExpressionAttributeValues[`:k${i}`] = row[k]
193
+ })
194
+ try {
195
+ const r = await client.send(
196
+ new UpdateCommand({
197
+ TableName: table,
198
+ Key: key(id),
199
+ ConditionExpression: 'attribute_exists(#id)',
200
+ UpdateExpression: `set ${keys.map((_, i) => `#k${i} = :k${i}`).join(', ')}`,
201
+ ExpressionAttributeNames,
202
+ ExpressionAttributeValues,
203
+ ReturnValues: 'ALL_NEW',
204
+ }),
205
+ )
206
+ return reading(r.Attributes!)
207
+ } catch (e) {
208
+ if ((e as { name?: string } | null)?.name === CONDITION) return null
209
+ throw e
210
+ }
211
+ },
212
+ async remove(id) {
213
+ return !!(
214
+ await client.send(
215
+ new DeleteCommand({ TableName: table, Key: key(id), ReturnValues: 'ALL_OLD' }),
216
+ )
217
+ ).Attributes
218
+ },
219
+ }
220
+ }
221
+
222
+ /** `db.adapter@1` over a DynamoDB table. */
223
+ export const adapter: DbAdapter<DynamoTarget> = {
224
+ name: 'dynamodb',
225
+ source: (t, spec) => dynamoSource(t, spec as DynamoSpec),
226
+ }
@@ -0,0 +1,157 @@
1
+ // A list source over a Firestore collection (the Admin SDK's `CollectionReference`, or anything shaped like it). The
2
+ // document id is the row's id. Firestore can't search inside a string, and a range is one field at a time, so `search`
3
+ // is a prefix on the first search column, and can't be combined with another sort.
4
+
5
+ import {
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
+ const NAME = '__name__',
19
+ HIGH = '',
20
+ IN_MAX = 30
21
+
22
+ /** One document, read. */
23
+ export interface FirestoreDoc {
24
+ id: string
25
+ exists: boolean
26
+ data(): object | undefined
27
+ }
28
+
29
+ /** Where one document lives. */
30
+ export interface FirestoreRef {
31
+ get(): Promise<FirestoreDoc>
32
+ create(data: object): Promise<unknown>
33
+ update(data: object): Promise<unknown>
34
+ delete(): Promise<unknown>
35
+ }
36
+
37
+ /** The Admin SDK's query, as far as a list builds one. */
38
+ export interface FirestoreQuery {
39
+ where(field: string, op: never, value: unknown): FirestoreQuery
40
+ orderBy(field: string, dir: 'asc' | 'desc'): FirestoreQuery
41
+ startAfter(...values: unknown[]): FirestoreQuery
42
+ offset(n: number): FirestoreQuery
43
+ limit(n: number): FirestoreQuery
44
+ count(): { get(): Promise<{ data(): { count: number } }> }
45
+ get(): Promise<{ docs: FirestoreDoc[] }>
46
+ }
47
+
48
+ /** The Admin SDK's `CollectionReference`, as far as a source calls it. */
49
+ export interface FirestoreCollection {
50
+ select(...fields: string[]): FirestoreQuery
51
+ doc(id?: string): FirestoreRef
52
+ }
53
+
54
+ type FirestoreList<Row> = {
55
+ collection: FirestoreCollection
56
+ spec: SourceSpec
57
+ stored: string[]
58
+ idColumn: string
59
+ idField: string
60
+ row: (doc: FirestoreDoc) => Row
61
+ }
62
+
63
+ async function listRows<Row>(p: ListParams, context: FirestoreList<Row>) {
64
+ const { collection, spec, stored, idColumn, idField, row } = context
65
+ const q = plan(spec, p)
66
+ let b = collection.select(...stored)
67
+ for (const w of q.where) {
68
+ if (w.values.length > IN_MAX)
69
+ throw new StartError('Q002', `Firestore takes ${IN_MAX} values in a filter`, 'ask for fewer')
70
+ b =
71
+ w.values.length === 1
72
+ ? b.where(w.column, '==' as never, w.values[0])
73
+ : b.where(w.column, 'in' as never, w.values)
74
+ }
75
+ let first = q.sort?.column === idColumn ? null : (q.sort?.column ?? null)
76
+ const dir = q.sort?.dir ?? 'asc'
77
+ if (q.search) {
78
+ const field = q.search.columns[0]!
79
+ if (first && first !== field)
80
+ throw new StartError(
81
+ 'Q002',
82
+ "Firestore can't search one field and sort by another",
83
+ 'drop one',
84
+ )
85
+ first = field
86
+ b = b
87
+ .where(field, '>=' as never, q.search.text)
88
+ .where(field, '<=' as never, q.search.text + HIGH)
89
+ }
90
+ const counted = b
91
+ if (first) b = b.orderBy(first, dir)
92
+ b = b.orderBy(NAME, dir)
93
+ if (p.after) b = first ? b.startAfter(p.after[0], p.after[1]) : b.startAfter(p.after[1])
94
+ const cursor = p.mode === 'cursor'
95
+ if (p.offset) b = b.offset(p.offset)
96
+ const rows = (await b.limit(cursor ? p.limit + 1 : p.limit).get()).docs.map(row)
97
+ const total = cursor ? undefined : (await counted.count().get()).data().count
98
+ return pageOf(
99
+ rows,
100
+ p,
101
+ {
102
+ sort:
103
+ q.sort?.field ??
104
+ (first ? Object.keys(spec.columns).find((k) => spec.columns[k] === first) : undefined),
105
+ id: idField,
106
+ },
107
+ total,
108
+ )
109
+ }
110
+
111
+ /** A `ListSource` over one collection, keyed by document id. */
112
+ export function firestoreSource<Row = Record<string, unknown>>(
113
+ collection: FirestoreCollection,
114
+ spec: SourceSpec,
115
+ ): ListSource<Row> {
116
+ const reading = rowOf<Row>(spec)
117
+ const idField = spec.id ?? 'id',
118
+ idColumn = storedId(spec)
119
+ const stored = Object.values(spec.columns).filter((c) => c !== idColumn)
120
+ const row = (doc: FirestoreDoc) => reading({ [idColumn]: doc.id, ...doc.data() })
121
+ const at = (id: unknown) => collection.doc(String(id))
122
+ return {
123
+ limits: { search: 'prefix' },
124
+ list(p: ListParams) {
125
+ return listRows(p, { collection, spec, stored, idColumn, idField, row })
126
+ },
127
+ async get(id) {
128
+ const doc = await at(id).get()
129
+ return doc.exists ? row(doc) : null
130
+ },
131
+ async create(data) {
132
+ const { [idColumn]: id, ...rest } = written(spec, data, true)
133
+ const ref = id === undefined ? collection.doc() : at(id)
134
+ await ref.create(rest)
135
+ return row(await ref.get())
136
+ },
137
+ async update(id, patch) {
138
+ const ref = at(id)
139
+ const body = written(spec, patch)
140
+ if (!(await ref.get()).exists) return null
141
+ if (Object.keys(body).length) await ref.update(body)
142
+ return row(await ref.get())
143
+ },
144
+ async remove(id) {
145
+ const ref = at(id)
146
+ if (!(await ref.get()).exists) return false
147
+ await ref.delete()
148
+ return true
149
+ },
150
+ }
151
+ }
152
+
153
+ /** `db.adapter@1` over a Firestore collection. */
154
+ export const adapter: DbAdapter<FirestoreCollection> = {
155
+ name: 'firestore',
156
+ source: (t, spec) => firestoreSource(t, spec),
157
+ }
package/src/kysely.ts ADDED
@@ -0,0 +1,162 @@
1
+ // A list source over Kysely. The types say nothing here: `table` and `columns` are strings, so Kysely's `dynamic`-free
2
+ // builder gets them from the spec, never from a request.
3
+
4
+ import type { ExpressionBuilder, Kysely, SelectQueryBuilder } from 'kysely'
5
+ import {
6
+ likeOf,
7
+ pageOf,
8
+ plan,
9
+ rowOf,
10
+ storedId,
11
+ written,
12
+ type DbAdapter,
13
+ type ListParams,
14
+ type ListSource,
15
+ type SourceSpec,
16
+ } from '@kerf-js/start/list'
17
+ import { StartError } from '@kerf-js/start/data'
18
+ import { driver } from './driver'
19
+
20
+ const { sql } = await driver('@kerf-js/db/kysely', 'kysely', () => import('kysely'))
21
+
22
+ /** A source's allowlist, its table, and whether the engine can `returning`. */
23
+ export interface KyselySpec extends SourceSpec {
24
+ table: string
25
+ /** MySQL has no `returning`. Default true. */
26
+ returning?: boolean
27
+ }
28
+
29
+ type Tables = Record<string, Record<string, unknown>>
30
+ type Eb = ExpressionBuilder<Tables, string>
31
+
32
+ type KyselyList<Row> = {
33
+ db: Kysely<Tables>
34
+ spec: KyselySpec
35
+ table: string
36
+ columns: string[]
37
+ idColumn: string
38
+ reading: (row: object) => Row
39
+ }
40
+
41
+ async function listRows<Row>(p: ListParams, context: KyselyList<Row>) {
42
+ const { db, spec, table, columns, idColumn, reading } = context
43
+ const q = plan(spec, p)
44
+ const filtered = <O>(from: SelectQueryBuilder<Tables, string, O>) => {
45
+ let b = from
46
+ for (const w of q.where) {
47
+ const some = w.values.filter((v) => v !== null)
48
+ b = b.where((eb: Eb) =>
49
+ eb.or([
50
+ ...(some.length ? [eb(w.column, 'in', some)] : []),
51
+ ...(w.values.includes(null) ? [eb(w.column, 'is', null)] : []),
52
+ ]),
53
+ )
54
+ }
55
+ if (q.search) {
56
+ const like = likeOf(q.search.text)
57
+ b = b.where((eb: Eb) =>
58
+ eb.or(
59
+ q.search!.columns.map((c) => sql<boolean>`lower(${sql.ref(c)}) like ${like} escape '!'`),
60
+ ),
61
+ )
62
+ }
63
+ return b
64
+ }
65
+ let b = filtered(db.selectFrom(table).select(columns))
66
+ const dir = q.sort?.dir === 'desc' ? 'desc' : 'asc',
67
+ cmp = dir === 'desc' ? '<' : '>'
68
+ if (p.after) {
69
+ const [value, id] = p.after
70
+ b = b.where((eb: Eb) =>
71
+ q.sort
72
+ ? eb.or([
73
+ eb(q.sort.column, cmp, value),
74
+ eb.and([eb(q.sort.column, '=', value), eb(idColumn, cmp, id)]),
75
+ ])
76
+ : eb(idColumn, '>', id),
77
+ )
78
+ }
79
+ b = q.sort ? b.orderBy(q.sort.column, dir).orderBy(idColumn, dir) : b.orderBy(idColumn, 'asc')
80
+ const cursor = p.mode === 'cursor'
81
+ const rows = (
82
+ await b
83
+ .limit(cursor ? p.limit + 1 : p.limit)
84
+ .offset(p.offset)
85
+ .execute()
86
+ ).map(reading)
87
+ const total = cursor
88
+ ? undefined
89
+ : Number(
90
+ (
91
+ await filtered(
92
+ db.selectFrom(table).select(sql<unknown>`count(*)`.as('n')),
93
+ ).executeTakeFirstOrThrow()
94
+ ).n,
95
+ )
96
+ return pageOf(rows, p, { sort: q.sort?.field, id: q.id.field }, total)
97
+ }
98
+
99
+ /** A `ListSource` over one table of any `Kysely<DB>`. */
100
+ export function kyselySource<Row = Record<string, unknown>, DB = unknown>(
101
+ handle: Kysely<DB>,
102
+ spec: KyselySpec,
103
+ ): ListSource<Row> {
104
+ const db = handle as unknown as Kysely<Tables>
105
+ const { table, returning = true } = spec
106
+ const columns = Object.values(spec.columns)
107
+ const reading = rowOf<Row>(spec)
108
+ const idColumn = storedId(spec)
109
+ const byId = async (id: unknown) => {
110
+ const r = await db.selectFrom(table).select(columns).where(idColumn, '=', id).executeTakeFirst()
111
+ return r ? reading(r) : null
112
+ }
113
+ return {
114
+ list(p: ListParams) {
115
+ return listRows(p, { db, spec, table, columns, idColumn, reading })
116
+ },
117
+ get: byId,
118
+ async create(data) {
119
+ const row = written(spec, data, true)
120
+ const id = row[idColumn]
121
+ if (returning)
122
+ return reading(
123
+ await db.insertInto(table).values(row).returning(columns).executeTakeFirstOrThrow(),
124
+ )
125
+ if (id === undefined)
126
+ throw new StartError(
127
+ 'Q002',
128
+ "`create` needs the id: MySQL can't return a row",
129
+ 'generate it before the insert',
130
+ )
131
+ await db.insertInto(table).values(row).execute()
132
+ return (await byId(id))!
133
+ },
134
+ async update(id, patch) {
135
+ const row = written(spec, patch)
136
+ if (!Object.keys(row).length) return byId(id)
137
+ if (returning) {
138
+ const r = await db
139
+ .updateTable(table)
140
+ .set(row)
141
+ .where(idColumn, '=', id)
142
+ .returning(columns)
143
+ .executeTakeFirst()
144
+ return r ? reading(r) : null
145
+ }
146
+ if (!(await byId(id))) return null
147
+ await db.updateTable(table).set(row).where(idColumn, '=', id).execute()
148
+ return byId(id)
149
+ },
150
+ async remove(id) {
151
+ return (
152
+ (await db.deleteFrom(table).where(idColumn, '=', id).executeTakeFirst()).numDeletedRows > 0n
153
+ )
154
+ },
155
+ }
156
+ }
157
+
158
+ /** `db.adapter@1` over a table of a Kysely instance. */
159
+ export const adapter: DbAdapter<Kysely<unknown>> = {
160
+ name: 'kysely',
161
+ source: (t, spec) => kyselySource(t, spec as KyselySpec),
162
+ }