@weft-js/db 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,16 @@
+MIT License
+
+Copyright (c) 2026 ravonus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# @weft-js/db
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Early release (0.1.1).** APIs will change between minor versions.
+
+Database layers and list sources for [`@weft-js/start`](../start). Each driver is an optional peer dependency, and each
+subpath loads only its own.
+
+You rarely install this by hand. `npm create @weft-js` and `weft add db` pick the layer and write the files:
+
+```bash
+npm create @weft-js my-app -- --db postgres --layer native
+npx weft add db sqlite --layer prisma   # in an existing app
+```
+
+`--db` takes `sqlite`, `postgres`, `mysql` or `none`. `--layer` takes `drizzle` (the default, which needs nothing from
+this package), `prisma` or `native`.
+
+## What's in it
+
+| Import | What it is |
+|---|---|
+| `@weft-js/db/plugin-native/<engine>` | `createDb({ url })`: a `sql` tag over the driver, with no ORM. Values always go to the driver as parameters. `<engine>` is `sqlite`, `postgres` or `mysql` |
+| `@weft-js/db/plugin-native/auth` | `nativeAuth(db)`: a Better Auth database adapter over that client |
+| `@weft-js/db/plugin-prisma` | `withWeft(client, dialect)`: the same Prisma client, with what weft needs to run its migrations and check its tags |
+| `@weft-js/db/sql`, `/kysely`, `/prisma`, `/mongo`, `/dynamodb`, `/firestore` | List sources: the rows behind a `query` that takes `listInput` from `@weft-js/start/list`, paged, filtered, sorted and searched |
+
+The layers and the list sources each have a `/plugin` subpath for `weft.config.ts`, so `weft check` and the plugin lock know it's there.
+
+## Docs
+
+`weft docs start` covers the database: `ctx.db`, migrations with `weft db generate`, and change feeds.

package/package.json

@@ -1,6 +1,86 @@
 {
   "name": "@weft-js/db",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "weft's data layers and list sources in one package: each driver is an optional peer, and a subpath loads only its own",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    "./sql": "./src/sql.ts",
+    "./sql/plugin": "./plugins/sql.mjs",
+    "./kysely": "./src/kysely.ts",
+    "./kysely/plugin": "./plugins/kysely.mjs",
+    "./prisma": "./src/prisma.ts",
+    "./prisma/plugin": "./plugins/prisma.mjs",
+    "./mongo": "./src/mongo.ts",
+    "./mongo/plugin": "./plugins/mongo.mjs",
+    "./dynamodb": "./src/dynamodb.ts",
+    "./dynamodb/plugin": "./plugins/dynamodb.mjs",
+    "./firestore": "./src/firestore.ts",
+    "./firestore/plugin": "./plugins/firestore.mjs",
+    "./plugin-native": "./src/native/index.ts",
+    "./plugin-native/sqlite": "./src/native/sqlite.ts",
+    "./plugin-native/postgres": "./src/native/postgres.ts",
+    "./plugin-native/mysql": "./src/native/mysql.ts",
+    "./plugin-native/auth": "./src/native/auth.ts",
+    "./plugin-native/plugin": "./plugins/native.mjs",
+    "./plugin-prisma": "./src/prisma-client.ts",
+    "./plugin-prisma/plugin": "./plugins/prisma-client.mjs"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-dynamodb": "^3.0.0",
+    "@aws-sdk/lib-dynamodb": "^3.0.0",
+    "@prisma/client": ">=6",
+    "@weft-js/start": "^0.1.1",
+    "better-auth": "^1.7.0",
+    "firebase-admin": ">=12",
+    "kysely": "^0.29.0",
+    "mongodb": ">=6",
+    "mysql2": "^3.24.0",
+    "postgres": ">=3",
+    "@weft-js/core": "^0.1.1"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-dynamodb": {
+      "optional": true
+    },
+    "@aws-sdk/lib-dynamodb": {
+      "optional": true
+    },
+    "@prisma/client": {
+      "optional": true
+    },
+    "better-auth": {
+      "optional": true
+    },
+    "firebase-admin": {
+      "optional": true
+    },
+    "kysely": {
+      "optional": true
+    },
+    "mongodb": {
+      "optional": true
+    },
+    "mysql2": {
+      "optional": true
+    },
+    "postgres": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "keywords": [
+    "weft"
+  ],
+  "files": [
+    "src",
+    "plugins",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/plugins/dynamodb.d.mts

@@ -0,0 +1,6 @@
+import type { PluginInstance } from '@weft-js/core/plugin'
+
+/** Binds the DynamoDB list source to `db.adapter@1`. */
+declare const plugin: (options?: Record<string, unknown>) => PluginInstance<unknown>
+/** Installed under `db.adapter@1` by `weft plugins sync`. */
+export default plugin

package/plugins/dynamodb.mjs

@@ -0,0 +1,17 @@
+// dynamoSource() for weft.config.ts: the `db.adapter` provider under the key `dynamodb`, so the lock records it and `weft check` names it.
+import { definePlugin, defineSlot, provide } from '@weft-js/core/plugin'
+
+const slot = defineSlot({ id: 'db.adapter', version: 1, cardinality: 'keyed', sides: ['server'] })
+
+export const dynamoSource = definePlugin({
+  name: '@weft-js/db/dynamodb',
+  version: '0.0.0',
+  weft: '*',
+  permissions: { net: ['driver:aws-sdk'] },
+  contribute: () => ({
+    provides: [provide(slot, { key: 'dynamodb', sides: { server: { module: '@weft-js/db/dynamodb', export: 'adapter' } } })],
+    agents: { title: 'Lists (dynamodb)', text: 'Build a source once, in a server module, with `columns`: only those are selected, returned or written. Then `query({ input: listInput({ sort, filter, search }), run: ({ input }) => source.list(input) })`. warp `Table` reads what comes back. Cursor mode only, and a sort needs a partition and an index.' },
+  }),
+})
+
+export default dynamoSource

package/plugins/firestore.d.mts

@@ -0,0 +1,6 @@
+import type { PluginInstance } from '@weft-js/core/plugin'
+
+/** Binds the Firestore list source to `db.adapter@1`. */
+declare const plugin: (options?: Record<string, unknown>) => PluginInstance<unknown>
+/** Installed under `db.adapter@1` by `weft plugins sync`. */
+export default plugin

package/plugins/firestore.mjs

@@ -0,0 +1,17 @@
+// firestoreSource() for weft.config.ts: the `db.adapter` provider under the key `firestore`, so the lock records it and `weft check` names it.
+import { definePlugin, defineSlot, provide } from '@weft-js/core/plugin'
+
+const slot = defineSlot({ id: 'db.adapter', version: 1, cardinality: 'keyed', sides: ['server'] })
+
+export const firestoreSource = definePlugin({
+  name: '@weft-js/db/firestore',
+  version: '0.0.0',
+  weft: '*',
+  permissions: { net: ['driver:firebase-admin'] },
+  contribute: () => ({
+    provides: [provide(slot, { key: 'firestore', sides: { server: { module: '@weft-js/db/firestore', export: 'adapter' } } })],
+    agents: { title: 'Lists (firestore)', text: 'Build a source once, in a server module, with `columns`: only those are selected, returned or written. Then `query({ input: listInput({ sort, filter, search }), run: ({ input }) => source.list(input) })`. warp `Table` reads what comes back. Search is by prefix on one field, and only without another sort.' },
+  }),
+})
+
+export default firestoreSource

package/plugins/kysely.d.mts

@@ -0,0 +1,6 @@
+import type { PluginInstance } from '@weft-js/core/plugin'
+
+/** Binds the Kysely list source to `db.adapter@1`. */
+declare const plugin: (options?: Record<string, unknown>) => PluginInstance<unknown>
+/** Installed under `db.adapter@1` by `weft plugins sync`. */
+export default plugin

package/plugins/kysely.mjs

@@ -0,0 +1,17 @@
+// kyselySource() for weft.config.ts: the `db.adapter` provider under the key `kysely`, so the lock records it and `weft check` names it.
+import { definePlugin, defineSlot, provide } from '@weft-js/core/plugin'
+
+const slot = defineSlot({ id: 'db.adapter', version: 1, cardinality: 'keyed', sides: ['server'] })
+
+export const kyselySource = definePlugin({
+  name: '@weft-js/db/kysely',
+  version: '0.0.0',
+  weft: '*',
+  permissions: { net: ['driver:kysely'] },
+  contribute: () => ({
+    provides: [provide(slot, { key: 'kysely', sides: { server: { module: '@weft-js/db/kysely', export: 'adapter' } } })],
+    agents: { title: 'Lists (kysely)', text: 'Build a source once, in a server module, with `columns`: only those are selected, returned or written. Then `query({ input: listInput({ sort, filter, search }), run: ({ input }) => source.list(input) })`. warp `Table` reads what comes back.' },
+  }),
+})
+
+export default kyselySource

package/plugins/mongo.d.mts

@@ -0,0 +1,6 @@
+import type { PluginInstance } from '@weft-js/core/plugin'
+
+/** Binds the MongoDB list source to `db.adapter@1`. */
+declare const plugin: (options?: Record<string, unknown>) => PluginInstance<unknown>
+/** Installed under `db.adapter@1` by `weft plugins sync`. */
+export default plugin

package/plugins/mongo.mjs

@@ -0,0 +1,17 @@
+// mongoSource() for weft.config.ts: the `db.adapter` provider under the key `mongo`, so the lock records it and `weft check` names it.
+import { definePlugin, defineSlot, provide } from '@weft-js/core/plugin'
+
+const slot = defineSlot({ id: 'db.adapter', version: 1, cardinality: 'keyed', sides: ['server'] })
+
+export const mongoSource = definePlugin({
+  name: '@weft-js/db/mongo',
+  version: '0.0.0',
+  weft: '*',
+  permissions: { net: ['driver:mongodb'] },
+  contribute: () => ({
+    provides: [provide(slot, { key: 'mongo', sides: { server: { module: '@weft-js/db/mongo', export: 'adapter' } } })],
+    agents: { title: 'Lists (mongo)', text: 'Build a source once, in a server module, with `columns`: only those are selected, returned or written. Then `query({ input: listInput({ sort, filter, search }), run: ({ input }) => source.list(input) })`. warp `Table` reads what comes back. `watchMongo` turns writes from anywhere into tag pokes.' },
+  }),
+})
+
+export default mongoSource

package/plugins/native.d.mts

@@ -0,0 +1,6 @@
+import type { PluginInstance } from '@weft-js/core/plugin'
+
+/** The no-ORM database client, as a plugin that fills `ctx.db`. */
+export const native: () => PluginInstance<unknown>
+/** The same as the named export. */
+export default native

package/plugins/native.mjs

@@ -0,0 +1,31 @@
+// native() for weft.config.ts (research 34 §4): the no-ORM data layer. It holds what the CLI needs: where migrations
+// live and how `weft db generate` starts one. The runtime is `@weft-js/db/plugin-native/<engine>`.
+import { mkdirSync, readdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { definePlugin } from '@weft-js/core/plugin'
+
+const DIR = 'migrations'
+
+/** A new, empty, numbered migration for you to write: with no schema there is nothing to diff. */
+function generate(root, name = 'change') {
+  const dir = join(root, DIR)
+  mkdirSync(dir, { recursive: true })
+  const next = readdirSync(dir).filter(f => f.endsWith('.sql')).length
+  const file = `${String(next).padStart(4, '0')}_${name.replace(/[^\w-]/g, '_')}.sql`
+  writeFileSync(join(dir, file), '-- Applies on the next request. Migrations run once, in file order.\n')
+  return `${DIR}/${file}`
+}
+
+export const native = definePlugin({
+  name: '@weft-js/db/plugin-native',
+  version: '0.0.0',
+  weft: '*',
+  permissions: { fs: { read: ['migrations/**'], write: ['migrations/**'] } },
+  contribute: () => ({
+    db: { layer: 'native', migrations: DIR, generate },
+    agents: { title: 'Database (Native)', text: 'No ORM: `ctx.db.sql` is a tagged template, and values are always bound, never concatenated. Rows are plain objects. `ctx.db.transaction(tx => …)` gives `tx.sql`, and `ctx.db.driver` is the real driver. `weft db generate <name>` starts a file in `migrations/`; write the SQL by hand. Validate input with your own Zod schemas.' },
+    map: [{ want: 'Change the database', call: '`weft db generate <name>`, then write the SQL in `migrations/`', have: 'no ORM' }],
+  }),
+})
+
+export default native

package/plugins/prisma-client.d.mts

@@ -0,0 +1,6 @@
+import type { PluginInstance } from '@weft-js/core/plugin'
+
+/** Prisma as the app's database client, as a plugin that fills `ctx.db`. */
+export const prisma: () => PluginInstance<unknown>
+/** The same as the named export. */
+export default prisma

package/plugins/prisma-client.mjs

@@ -0,0 +1,45 @@
+// prisma() for weft.config.ts (research 34 §4): what the CLI needs from Prisma. `weft db generate` writes the client and
+// a migration into `prisma/migrations`. The first needs no database; later ones are Prisma's own diff, which does.
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { definePlugin } from '@weft-js/core/plugin'
+
+const DIR = 'prisma/migrations'
+
+function run(root, args) {
+  let bin
+  try {
+    bin = join(dirname(createRequire(join(root, 'package.json')).resolve('prisma/package.json')), 'build/index.js')
+  } catch {
+    throw Object.assign(new Error('prisma is not installed in this project'), { code: 'E_USAGE' })
+  }
+  const r = spawnSync(process.execPath, [bin, ...args], { cwd: root, encoding: 'utf8' })
+  if (r.status !== 0) throw Object.assign(new Error(`prisma ${args[0]} failed:\n${r.stdout}${r.stderr}`), { code: 'E_INTERNAL' })
+  return r.stdout
+}
+
+function generate(root, name = 'change') {
+  run(root, ['generate'])
+  if (existsSync(join(root, DIR))) return run(root, ['migrate', 'dev', '--create-only', '--name', name]).trim()
+  const sql = run(root, ['migrate', 'diff', '--from-empty', '--to-schema', 'prisma/schema.prisma', '--script'])
+  const dir = join(root, DIR, '00000000000000_init')
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, 'migration.sql'), sql)
+  return `${DIR}/00000000000000_init/migration.sql`
+}
+
+export const prisma = definePlugin({
+  name: '@weft-js/db/plugin-prisma',
+  version: '0.0.0',
+  weft: '*',
+  permissions: { fs: { read: ['prisma/**'], write: ['prisma/migrations/**'] }, spawn: ['node'] },
+  contribute: () => ({
+    db: { layer: 'prisma', schema: 'prisma/schema.prisma', migrations: DIR, generate },
+    agents: { title: 'Database (Prisma)', text: '`ctx.db` is the real Prisma client, so Prisma\'s docs apply. The schema is `prisma/schema.prisma`; after changing it, run `weft db generate <name>`, which updates the client and adds a migration that applies on the next request.' },
+    map: [{ want: 'Change the database', call: 'Edit `prisma/schema.prisma`, then `weft db generate <name>`', have: 'Prisma' }],
+  }),
+})
+
+export default prisma

package/plugins/prisma.d.mts

@@ -0,0 +1,6 @@
+import type { PluginInstance } from '@weft-js/core/plugin'
+
+/** Binds the Prisma list source to `db.adapter@1`. */
+declare const plugin: (options?: Record<string, unknown>) => PluginInstance<unknown>
+/** Installed under `db.adapter@1` by `weft plugins sync`. */
+export default plugin

package/plugins/prisma.mjs

@@ -0,0 +1,17 @@
+// prismaSource() for weft.config.ts: the `db.adapter` provider under the key `prisma`, so the lock records it and `weft check` names it.
+import { definePlugin, defineSlot, provide } from '@weft-js/core/plugin'
+
+const slot = defineSlot({ id: 'db.adapter', version: 1, cardinality: 'keyed', sides: ['server'] })
+
+export const prismaSource = definePlugin({
+  name: '@weft-js/db/prisma',
+  version: '0.0.0',
+  weft: '*',
+  permissions: { net: ['driver:prisma'] },
+  contribute: () => ({
+    provides: [provide(slot, { key: 'prisma', sides: { server: { module: '@weft-js/db/prisma', export: 'adapter' } } })],
+    agents: { title: 'Lists (prisma)', text: 'Build a source once, in a server module, with `columns`: only those are selected, returned or written. Then `query({ input: listInput({ sort, filter, search }), run: ({ input }) => source.list(input) })`. warp `Table` reads what comes back.' },
+  }),
+})
+
+export default prismaSource

package/plugins/sql.d.mts

@@ -0,0 +1,6 @@
+import type { PluginInstance } from '@weft-js/core/plugin'
+
+/** Binds the bound-SQL list source to `db.adapter@1`. */
+declare const plugin: (options?: Record<string, unknown>) => PluginInstance<unknown>
+/** Installed under `db.adapter@1` by `weft plugins sync`. */
+export default plugin

package/plugins/sql.mjs

@@ -0,0 +1,17 @@
+// sqlSource() for weft.config.ts: the `db.adapter` provider under the key `sql`, so the lock records it and `weft check` names it.
+import { definePlugin, defineSlot, provide } from '@weft-js/core/plugin'
+
+const slot = defineSlot({ id: 'db.adapter', version: 1, cardinality: 'keyed', sides: ['server'] })
+
+export const sqlSource = definePlugin({
+  name: '@weft-js/db/sql',
+  version: '0.0.0',
+  weft: '*',
+  permissions: { net: ['driver:query'] },
+  contribute: () => ({
+    provides: [provide(slot, { key: 'sql', sides: { server: { module: '@weft-js/db/sql', export: 'adapter' } } })],
+    agents: { title: 'Lists (sql)', text: 'Build a source once, in a server module, with `columns`: only those are selected, returned or written. Then `query({ input: listInput({ sort, filter, search }), run: ({ input }) => source.list(input) })`. warp `Table` reads what comes back.' },
+  }),
+})
+
+export default sqlSource

package/src/driver.ts

@@ -0,0 +1,20 @@
+// Each driver is an optional peer: nobody installs Prisma or Mongo to use SQLite. A subpath that needs one loads it here,
+// at the top of its own module, so a missing driver says what to install instead of failing somewhere in a bundle.
+
+const MISSING = new Set(['ERR_MODULE_NOT_FOUND', 'MODULE_NOT_FOUND'])
+
+/** True when this failure is `pkg` itself not being there, not something inside it failing to load. */
+const isMissing = (error: unknown, pkg: string) => {
+  const { code = '', message } = (error ?? {}) as { code?: string; message?: unknown }
+  return (MISSING.has(code) || /cannot find (module|package)|failed to (load|resolve)/i.test(String(message))) && String(message).includes(pkg)
+}
+
+/** `await driver('@weft-js/db/kysely', 'kysely', () => import('kysely'))`. The import stays literal so a bundler still sees it. */
+export async function driver<T>(subpath: string, pkg: string, load: () => Promise<T>): Promise<T> {
+  try {
+    return await load()
+  } catch (error) {
+    if (isMissing(error, pkg)) throw new Error(`${subpath} needs the \`${pkg}\` driver, which isn't installed. Run: npm install ${pkg}`, { cause: error })
+    throw error
+  }
+}

package/src/dynamodb.ts

@@ -0,0 +1,110 @@
+// A list source over a DynamoDB table, through a `DynamoDBDocumentClient`. DynamoDB has no offset and sorts only inside a
+// partition, so this is cursor mode only: a `Scan` by default, and a `Query` when `partition` and `sortKey` name an index.
+
+import { pageOf, plan, rowOf, storedId, written, type DbAdapter, type ListParams, type ListSource, type SourceSpec } from '@weft-js/start/list'
+import { StartError } from '@weft-js/start/data'
+import { driver } from './driver'
+
+const { DeleteCommand, GetCommand, PutCommand, QueryCommand, ScanCommand, UpdateCommand } = await driver('@weft-js/db/dynamodb', '@aws-sdk/lib-dynamodb', () => import('@aws-sdk/lib-dynamodb'))
+
+type Item = Record<string, unknown>
+
+/** What a command answers, as far as a source reads it. */
+export interface DynamoReply { Item?: Item | undefined; Items?: Item[] | undefined; Attributes?: Item | undefined; LastEvaluatedKey?: Item | undefined }
+
+/** A `DynamoDBDocumentClient`, or anything else that sends these commands, and the table to send them to. */
+export interface DynamoTarget { client: { send(command: object): Promise<DynamoReply> }; table: string }
+
+/** A source's allowlist, and the index that lets a list sort. */
+export interface DynamoSpec extends SourceSpec {
+  /** With `sortKey`: list one partition through `index`, sorted. */
+  partition?: { column: string; value: unknown }
+  /** The public name of the index's sort key: the one thing that can be sorted on. */
+  sortKey?: string
+  index?: string
+}
+
+const CONDITION = 'ConditionalCheckFailedException'
+const PAGE = 1 << 12
+
+/** A `ListSource` over one table, in cursor mode. */
+export function dynamoSource<Row = Record<string, unknown>>({ client, table }: DynamoTarget, spec: DynamoSpec): ListSource<Row> {
+  const reading = rowOf<Row>(spec)
+  const idField = spec.id ?? 'id', idColumn = storedId(spec)
+  const key = (id: unknown) => ({ [idColumn]: id })
+  const sortColumn = spec.sortKey && spec.columns[spec.sortKey]
+  const stored = Object.values(spec.columns)
+  const projection = stored.map((_, i) => `#c${i}`).join(', ')
+  const names = Object.fromEntries(stored.map((c, i) => [`#c${i}`, c]))
+  const byId = async (id: unknown) => {
+    const r = await client.send(new GetCommand({ TableName: table, Key: key(id), ConsistentRead: true }))
+    return r.Item ? reading(r.Item) : null
+  }
+  return {
+    limits: { page: false, search: 'cased', sort: spec.sortKey ? [spec.sortKey] : [] },
+    async list(p: ListParams) {
+      if (p.mode === 'page') throw new StartError('Q002', 'DynamoDB has no offset', 'ask for `mode: \'cursor\'`')
+      const q = plan(spec, p)
+      if (q.sort && q.sort.field !== spec.sortKey) throw new StartError('Q002', `DynamoDB can sort only on the index's key, not \`${q.sort.field}\``, 'set `sortKey`')
+      const values: Record<string, unknown> = {}, ExpressionAttributeNames: Record<string, string> = { ...names }
+      let n = 0
+      const value = (v: unknown) => { const k = `:v${n++}`; values[k] = v; return k }
+      const name = (c: string) => { const k = `#n${n++}`; ExpressionAttributeNames[k] = c; return k }
+      const parts = q.where.map(w => {
+        const col = name(w.column)
+        return `(${w.values.map(v => (v === null ? `attribute_not_exists(${col})` : `${col} = ${value(v)}`)).join(' or ')})`
+      })
+      if (q.search) {
+        const v = value(q.search.text)
+        parts.push(`(${q.search.columns.map(c => `contains(${name(c)}, ${v})`).join(' or ')})`)
+      }
+      const query = spec.partition && sortColumn
+      const KeyConditionExpression = query ? `${name(spec.partition!.column)} = ${value(spec.partition!.value)}` : undefined
+      const start = p.after ? { [idColumn]: p.after[1], ...(query ? { [spec.partition!.column]: spec.partition!.value, [sortColumn]: p.after[0] } : {}) } : undefined
+      const rows: Item[] = []
+      let ExclusiveStartKey: Item | undefined = start
+      // `Limit` counts what's read before the filter, so a page can take several trips.
+      do {
+        const input = {
+          TableName: table,
+          ProjectionExpression: projection,
+          ExpressionAttributeNames,
+          ...(Object.keys(values).length ? { ExpressionAttributeValues: values } : {}),
+          ...(parts.length ? { FilterExpression: parts.join(' and ') } : {}),
+          ...(ExclusiveStartKey ? { ExclusiveStartKey } : {}),
+          Limit: PAGE,
+        }
+        const r: DynamoReply = await client.send(query ? new QueryCommand({ ...input, IndexName: spec.index, KeyConditionExpression, ScanIndexForward: q.sort?.dir !== 'desc' }) : new ScanCommand(input))
+        rows.push(...(r.Items ?? []))
+        ExclusiveStartKey = r.LastEvaluatedKey
+      } while (ExclusiveStartKey && rows.length <= p.limit)
+      return pageOf(rows.slice(0, p.limit + 1).map(reading), p, { sort: q.sort?.field ?? spec.sortKey, id: idField })
+    },
+    get: byId,
+    async create(data) {
+      const Item = { ...written(spec, data, true), ...(spec.partition ? { [spec.partition.column]: spec.partition.value } : {}) }
+      await client.send(new PutCommand({ TableName: table, Item }))
+      return reading(Item)
+    },
+    async update(id, patch) {
+      const row = written(spec, patch)
+      const keys = Object.keys(row)
+      if (!keys.length) return byId(id)
+      const ExpressionAttributeNames: Record<string, string> = { '#id': idColumn }, ExpressionAttributeValues: Record<string, unknown> = {}
+      keys.forEach((k, i) => { ExpressionAttributeNames[`#k${i}`] = k; ExpressionAttributeValues[`:k${i}`] = row[k] })
+      try {
+        const r = await client.send(new UpdateCommand({ TableName: table, Key: key(id), ConditionExpression: 'attribute_exists(#id)', UpdateExpression: `set ${keys.map((_, i) => `#k${i} = :k${i}`).join(', ')}`, ExpressionAttributeNames, ExpressionAttributeValues, ReturnValues: 'ALL_NEW' }))
+        return reading(r.Attributes!)
+      } catch (e) {
+        if ((e as { name?: string } | null)?.name === CONDITION) return null
+        throw e
+      }
+    },
+    async remove(id) {
+      return !!(await client.send(new DeleteCommand({ TableName: table, Key: key(id), ReturnValues: 'ALL_OLD' }))).Attributes
+    },
+  }
+}
+
+/** `db.adapter@1` over a DynamoDB table. */
+export const adapter: DbAdapter<DynamoTarget> = { name: 'dynamodb', source: (t, spec) => dynamoSource(t, spec as DynamoSpec) }

package/src/firestore.ts

@@ -0,0 +1,99 @@
+// A list source over a Firestore collection (the Admin SDK's `CollectionReference`, or anything shaped like it). The
+// 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`
+// is a prefix on the first search column, and can't be combined with another sort.
+
+import { pageOf, plan, rowOf, storedId, written, type DbAdapter, type ListParams, type ListSource, type SourceSpec } from '@weft-js/start/list'
+import { StartError } from '@weft-js/start/data'
+
+const NAME = '__name__', HIGH = '', IN_MAX = 30
+
+/** One document, read. */
+export interface FirestoreDoc { id: string; exists: boolean; data(): object | undefined }
+
+/** Where one document lives. */
+export interface FirestoreRef {
+  get(): Promise<FirestoreDoc>
+  create(data: object): Promise<unknown>
+  update(data: object): Promise<unknown>
+  delete(): Promise<unknown>
+}
+
+/** The Admin SDK's query, as far as a list builds one. */
+export interface FirestoreQuery {
+  where(field: string, op: never, value: unknown): FirestoreQuery
+  orderBy(field: string, dir: 'asc' | 'desc'): FirestoreQuery
+  startAfter(...values: unknown[]): FirestoreQuery
+  offset(n: number): FirestoreQuery
+  limit(n: number): FirestoreQuery
+  count(): { get(): Promise<{ data(): { count: number } }> }
+  get(): Promise<{ docs: FirestoreDoc[] }>
+}
+
+/** The Admin SDK's `CollectionReference`, as far as a source calls it. */
+export interface FirestoreCollection {
+  select(...fields: string[]): FirestoreQuery
+  doc(id?: string): FirestoreRef
+}
+
+/** A `ListSource` over one collection, keyed by document id. */
+export function firestoreSource<Row = Record<string, unknown>>(collection: FirestoreCollection, spec: SourceSpec): ListSource<Row> {
+  const reading = rowOf<Row>(spec)
+  const idField = spec.id ?? 'id', idColumn = storedId(spec)
+  const stored = Object.values(spec.columns).filter(c => c !== idColumn)
+  const row = (doc: FirestoreDoc) => reading({ [idColumn]: doc.id, ...doc.data() })
+  const at = (id: unknown) => collection.doc(String(id))
+  return {
+    limits: { search: 'prefix' },
+    async list(p: ListParams) {
+      const q = plan(spec, p)
+      let b = collection.select(...stored)
+      for (const w of q.where) {
+        if (w.values.length > IN_MAX) throw new StartError('Q002', `Firestore takes ${IN_MAX} values in a filter`, 'ask for fewer')
+        b = w.values.length === 1 ? b.where(w.column, '==' as never, w.values[0]) : b.where(w.column, 'in' as never, w.values)
+      }
+      let first = q.sort?.column === idColumn ? null : q.sort?.column ?? null
+      const dir = q.sort?.dir ?? 'asc'
+      if (q.search) {
+        const field = q.search.columns[0]!
+        if (first && first !== field) throw new StartError('Q002', 'Firestore can\'t search one field and sort by another', 'drop one')
+        first = field
+        b = b.where(field, '>=' as never, q.search.text).where(field, '<=' as never, q.search.text + HIGH)
+      }
+      const counted = b
+      if (first) b = b.orderBy(first, dir)
+      b = b.orderBy(NAME, dir)
+      if (p.after) b = first ? b.startAfter(p.after[0], p.after[1]) : b.startAfter(p.after[1])
+      const cursor = p.mode === 'cursor'
+      if (p.offset) b = b.offset(p.offset)
+      const rows = (await b.limit(cursor ? p.limit + 1 : p.limit).get()).docs.map(row)
+      const total = cursor ? undefined : (await counted.count().get()).data().count
+      return pageOf(rows, p, { sort: q.sort?.field ?? (first ? Object.keys(spec.columns).find(k => spec.columns[k] === first) : undefined), id: idField }, total)
+    },
+    async get(id) {
+      const doc = await at(id).get()
+      return doc.exists ? row(doc) : null
+    },
+    async create(data) {
+      const { [idColumn]: id, ...rest } = written(spec, data, true)
+      const ref = id === undefined ? collection.doc() : at(id)
+      await ref.create(rest)
+      return row(await ref.get())
+    },
+    async update(id, patch) {
+      const ref = at(id)
+      const body = written(spec, patch)
+      if (!(await ref.get()).exists) return null
+      if (Object.keys(body).length) await ref.update(body)
+      return row(await ref.get())
+    },
+    async remove(id) {
+      const ref = at(id)
+      if (!(await ref.get()).exists) return false
+      await ref.delete()
+      return true
+    },
+  }
+}
+
+/** `db.adapter@1` over a Firestore collection. */
+export const adapter: DbAdapter<FirestoreCollection> = { name: 'firestore', source: (t, spec) => firestoreSource(t, spec) }