@weft-js/start 0.1.1 → 0.1.2

package/src/list-drizzle.ts

@@ -1,21 +1,67 @@
 // The `db.adapter@1` default (research 13 §2.2): a list source over a Drizzle table. `columns` keeps its meaning here,
 // so a table's other columns stay out of what's selected, returned or written.
 
-import { and, asc, count, desc, eq, gt, inArray, isNull, lt, or, sql, type Column, type SQL } from 'drizzle-orm'
-import { likeOf, pageOf, plan, rowOf, storedId, written, type DbAdapter, type ListPage, type ListParams, type ListSource, type SourceSpec } from './list'
+import {
+  and,
+  asc,
+  count,
+  desc,
+  eq,
+  gt,
+  inArray,
+  isNull,
+  lt,
+  or,
+  sql,
+  type Column,
+  type SQL,
+} from 'drizzle-orm'
+import {
+  likeOf,
+  pageOf,
+  plan,
+  rowOf,
+  storedId,
+  written,
+  type DbAdapter,
+  type ListPage,
+  type ListParams,
+  type ListSource,
+  type SourceSpec,
+} from './list'
 
 /** The Drizzle client and table a list source runs on. */
-export interface DrizzleTarget { db: object; table: object }
+export interface DrizzleTarget {
+  db: object
+  table: object
+}
 
 /** What every dialect's query builders share by name, though no type says so. */
-type Chain = PromiseLike<object[]> & { from(t: object): Chain; where(w?: SQL): Chain; orderBy(...o: SQL[]): Chain; limit(n: number): Chain; offset(n: number): Chain; values(v: object): Chain; set(v: object): Chain; returning(s?: object): Chain }
-interface Db { select(s: object): Chain; insert(t: object): Chain; update(t: object): Chain; delete(t: object): Chain }
+type Chain = PromiseLike<object[]> & {
+  from(t: object): Chain
+  where(w?: SQL): Chain
+  orderBy(...o: SQL[]): Chain
+  limit(n: number): Chain
+  offset(n: number): Chain
+  values(v: object): Chain
+  set(v: object): Chain
+  returning(s?: object): Chain
+}
+interface Db {
+  select(s: object): Chain
+  insert(t: object): Chain
+  update(t: object): Chain
+  delete(t: object): Chain
+}
 
 /** A `ListSource` over a Drizzle table. */
-export function drizzleSource<Row = Record<string, unknown>>({ db: handle, table }: DrizzleTarget, spec: SourceSpec): ListSource<Row> {
+export function drizzleSource<Row = Record<string, unknown>>(
+  { db: handle, table }: DrizzleTarget,
+  spec: SourceSpec,
+): ListSource<Row> {
   const db = handle as Db
   const col = (name: string) => (table as Record<string, Column>)[name]!
-  const selection = Object.fromEntries(Object.values(spec.columns).map(c => [c, col(c)]))
+  const selection = Object.fromEntries(Object.values(spec.columns).map((c) => [c, col(c)]))
   const public_ = rowOf<Row>(spec)
   const id = col(storedId(spec))
   const reading = (rows: object[]) => rows.map(public_)
@@ -23,26 +69,66 @@ export function drizzleSource<Row = Record<string, unknown>>({ db: handle, table
   return {
     async list(p: ListParams): Promise<ListPage<Row>> {
       const q = plan(spec, p)
-      const filters: (SQL | undefined)[] = q.where.map(w => {
-        const some = w.values.filter(v => v !== null)
-        const hit = some.length === 1 ? eq(col(w.column), some[0]) : some.length ? inArray(col(w.column), some) : undefined
+      const filters: (SQL | undefined)[] = q.where.map((w) => {
+        const some = w.values.filter((v) => v !== null)
+        const hit =
+          some.length === 1
+            ? eq(col(w.column), some[0])
+            : some.length
+              ? inArray(col(w.column), some)
+              : undefined
         return w.values.includes(null) ? or(hit, isNull(col(w.column))) : hit
       })
-      if (q.search) filters.push(or(...q.search.columns.map(c => sql`lower(${col(c)}) like ${likeOf(q.search!.text)} escape '!'`)))
+      if (q.search)
+        filters.push(
+          or(
+            ...q.search.columns.map(
+              (c) => sql`lower(${col(c)}) like ${likeOf(q.search!.text)} escape '!'`,
+            ),
+          ),
+        )
       const where = and(...filters)
       const by = q.sort?.dir === 'desc' ? desc : asc
       const past = q.sort?.dir === 'desc' ? lt : gt
-      const keyset = p.after ? (q.sort ? or(past(col(q.sort.column), p.after[0]), and(eq(col(q.sort.column), p.after[0]), past(id, p.after[1]))) : past(id, p.after[1])) : undefined
+      const keyset = p.after
+        ? q.sort
+          ? or(
+              past(col(q.sort.column), p.after[0]),
+              and(eq(col(q.sort.column), p.after[0]), past(id, p.after[1])),
+            )
+          : past(id, p.after[1])
+        : undefined
       const order = q.sort ? [by(col(q.sort.column)), by(id)] : [asc(id)]
       const cursor = p.mode === 'cursor'
-      const rows = await db.select(selection).from(table).where(and(where, keyset)).orderBy(...order).limit(cursor ? p.limit + 1 : p.limit).offset(p.offset)
-      const total = cursor ? undefined : ((await db.select({ n: count() }).from(table).where(where)) as { n: number }[])[0]!.n
+      const rows = await db
+        .select(selection)
+        .from(table)
+        .where(and(where, keyset))
+        .orderBy(...order)
+        .limit(cursor ? p.limit + 1 : p.limit)
+        .offset(p.offset)
+      const total = cursor
+        ? undefined
+        : ((await db.select({ n: count() }).from(table).where(where)) as { n: number }[])[0]!.n
       return pageOf(reading(rows), p, { sort: q.sort?.field, id: q.id.field }, total)
     },
-    get: id_ => one(db.select(selection).from(table).where(eq(id, id_)).limit(1)),
-    create: async data => (await one(db.insert(table).values(written(spec, data, true)).returning(selection)))!,
-    update: (id_, patch) => { const row = written(spec, patch); return one(Object.keys(row).length ? db.update(table).set(row).where(eq(id, id_)).returning(selection) : db.select(selection).from(table).where(eq(id, id_)).limit(1)) },
-    remove: async id_ => (await db.delete(table).where(eq(id, id_)).returning({ id })).length > 0,
+    get: (id_) => one(db.select(selection).from(table).where(eq(id, id_)).limit(1)),
+    create: async (data) =>
+      (await one(
+        db
+          .insert(table)
+          .values(written(spec, data, true))
+          .returning(selection),
+      ))!,
+    update: (id_, patch) => {
+      const row = written(spec, patch)
+      return one(
+        Object.keys(row).length
+          ? db.update(table).set(row).where(eq(id, id_)).returning(selection)
+          : db.select(selection).from(table).where(eq(id, id_)).limit(1),
+      )
+    },
+    remove: async (id_) => (await db.delete(table).where(eq(id, id_)).returning({ id })).length > 0,
   }
 }
 

package/src/list.ts

@@ -17,7 +17,10 @@ export type Scalar = string | number | boolean | null
 /** Which way a sort runs. */
 export type Dir = 'asc' | 'desc'
 /** One field and a direction. */
-export interface Sort { field: string; dir: Dir }
+export interface Sort {
+  field: string
+  dir: Dir
+}
 
 /** A checked request, as a source takes it. */
 export interface ListParams {
@@ -33,8 +36,13 @@ export interface ListParams {
   filter: Record<string, Scalar | Scalar[]>
 }
 
-/** The envelope warp's `Table` reads. `next` and `prev` go back in as `cursor` or `page`; absent means no such page. */
-export interface ListPage<T> { items: T[]; total?: number; next?: string | number; prev?: string | number }
+/** The envelope Warp's `Table` reads. `next` and `prev` go back in as `cursor` or `page`; absent means no such page. */
+export interface ListPage<T> {
+  items: T[]
+  total?: number
+  next?: string | number
+  prev?: string | number
+}
 
 /** What a list lets a client ask for. */
 export interface ListSpec {
@@ -57,28 +65,42 @@ export interface ListRequest {
   filter?: Record<string, Scalar | Scalar[]>
 }
 
-const SEARCH_MAX = 200, IN_MAX = 100, CURSOR_MAX = 1024
+const SEARCH_MAX = 200,
+  IN_MAX = 100,
+  CURSOR_MAX = 1024
 
-const scalar = (v: unknown): v is Scalar => v === null || typeof v === 'boolean' || typeof v === 'string' || (typeof v === 'number' && Number.isFinite(v))
+const scalar = (v: unknown): v is Scalar =>
+  v === null ||
+  typeof v === 'boolean' ||
+  typeof v === 'string' ||
+  (typeof v === 'number' && Number.isFinite(v))
 
 const pack = (v: unknown) => (v instanceof Date ? { $d: v.toISOString() } : v)
-const stamped = (v: unknown): v is { $d: string } => typeof (v as { $d?: unknown } | null)?.$d === 'string'
+const stamped = (v: unknown): v is { $d: string } =>
+  typeof (v as { $d?: unknown } | null)?.$d === 'string'
 const unpack = (v: unknown) => (stamped(v) ? new Date(v.$d) : v)
 
 /** Opaque to a client, and read with the same care as any other input. */
 export function encodeCursor(value: unknown, id: unknown): string {
   const bytes = new TextEncoder().encode(JSON.stringify([pack(value), pack(id)]))
-  return btoa(String.fromCharCode(...bytes)).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '')
+  return btoa(String.fromCharCode(...bytes))
+    .replaceAll('+', '-')
+    .replaceAll('/', '_')
+    .replace(/=+$/, '')
 }
 
 /** The other way from `encodeCursor`: null for anything that isn't a cursor of ours. */
 export function decodeCursor(text: string): [unknown, unknown] | null {
   if (text.length > CURSOR_MAX) return null
   try {
-    const bytes = Uint8Array.from(atob(text.replaceAll('-', '+').replaceAll('_', '/')), c => c.charCodeAt(0))
+    const bytes = Uint8Array.from(atob(text.replaceAll('-', '+').replaceAll('_', '/')), (c) =>
+      c.charCodeAt(0),
+    )
     const list: unknown = JSON.parse(new TextDecoder().decode(bytes))
     const fits = (v: unknown) => scalar(v) || (stamped(v) && !Number.isNaN(Date.parse(v.$d)))
-    return Array.isArray(list) && list.length === 2 && list.every(fits) ? [unpack(list[0]), unpack(list[1])] : null
+    return Array.isArray(list) && list.length === 2 && list.every(fits)
+      ? [unpack(list[0]), unpack(list[1])]
+      : null
   } catch {
     return null
   }
@@ -86,38 +108,68 @@ export function decodeCursor(text: string): [unknown, unknown] | null {
 
 /** A `query`'s `input`. Takes a `ListRequest` from the client, and hands `run` the `ListParams` a source takes. */
 export function listInput(spec: ListSpec): StandardSchemaV1<ListRequest | undefined, ListParams> {
-  const fallback = spec.pageSize?.default ?? 25, max = spec.pageSize?.max ?? 100
-  const sorts = new Set(spec.sort), filters = new Set(spec.filter)
+  const fallback = spec.pageSize?.default ?? 25,
+    max = spec.pageSize?.max ?? 100
+  const sorts = new Set(spec.sort),
+    filters = new Set(spec.filter)
   const validate = (input: unknown) => {
     const issues: { message: string; path?: string[] }[] = []
     const no = (message: string, ...path: string[]) => void issues.push({ message, path })
     const r = (input ?? {}) as ListRequest
-    if (typeof r !== 'object' || Array.isArray(r)) return { issues: [{ message: 'a list request is an object' }] }
+    if (typeof r !== 'object' || Array.isArray(r))
+      return { issues: [{ message: 'a list request is an object' }] }
     const mode = r.mode ?? (r.cursor !== undefined ? 'cursor' : 'page')
     if (mode !== 'page' && mode !== 'cursor') no('`mode` is `page` or `cursor`', 'mode')
     const size = r.pageSize ?? fallback
-    if (!Number.isInteger(size) || size < 1 || size > max) no(`\`pageSize\` is a whole number up to ${max}`, 'pageSize')
+    if (!Number.isInteger(size) || size < 1 || size > max)
+      no(`\`pageSize\` is a whole number up to ${max}`, 'pageSize')
     const page = r.page ?? 1
-    if (!Number.isInteger(page) || page < 1 || page > 1e6) no('`page` is a whole number from 1', 'page')
+    if (!Number.isInteger(page) || page < 1 || page > 1e6)
+      no('`page` is a whole number from 1', 'page')
     let after: ListParams['after'] = null
     if (r.cursor != null) {
       after = typeof r.cursor === 'string' ? decodeCursor(r.cursor) : null
       if (!after) no('that cursor is not one of ours', 'cursor')
     }
     const sort = r.sort ?? spec.defaultSort ?? null
-    if (sort && !(typeof sort === 'object' && sorts.has(sort.field) && (sort.dir === 'asc' || sort.dir === 'desc'))) no('that sort is not allowed', 'sort')
-    if (r.search !== undefined && (typeof r.search !== 'string' || r.search.length > SEARCH_MAX)) no(`\`search\` is text up to ${SEARCH_MAX} characters`, 'search')
+    if (
+      sort &&
+      !(
+        typeof sort === 'object' &&
+        sorts.has(sort.field) &&
+        (sort.dir === 'asc' || sort.dir === 'desc')
+      )
+    )
+      no('that sort is not allowed', 'sort')
+    if (r.search !== undefined && (typeof r.search !== 'string' || r.search.length > SEARCH_MAX))
+      no(`\`search\` is text up to ${SEARCH_MAX} characters`, 'search')
     if (r.search && !spec.search?.length) no('this list has no search', 'search')
     const filter: ListParams['filter'] = Object.create(null)
-    if (r.filter !== undefined && (typeof r.filter !== 'object' || r.filter === null || Array.isArray(r.filter))) no('`filter` is an object', 'filter')
-    else for (const key of Object.keys(r.filter ?? {})) {
-      const v = r.filter![key]!
-      if (!filters.has(key)) no(`\`${key}\` can't be filtered on`, 'filter', key)
-      else if (Array.isArray(v) ? !(v.length && v.length <= IN_MAX && v.every(scalar)) : !scalar(v)) no(`\`${key}\` takes a value or a list of up to ${IN_MAX}, not an object`, 'filter', key)
-      else filter[key] = v
-    }
+    if (
+      r.filter !== undefined &&
+      (typeof r.filter !== 'object' || r.filter === null || Array.isArray(r.filter))
+    )
+      no('`filter` is an object', 'filter')
+    else
+      for (const key of Object.keys(r.filter ?? {})) {
+        const v = r.filter![key]!
+        if (!filters.has(key)) no(`\`${key}\` can't be filtered on`, 'filter', key)
+        else if (
+          Array.isArray(v) ? !(v.length && v.length <= IN_MAX && v.every(scalar)) : !scalar(v)
+        )
+          no(`\`${key}\` takes a value or a list of up to ${IN_MAX}, not an object`, 'filter', key)
+        else filter[key] = v
+      }
     if (issues.length) return { issues }
-    const params: ListParams = { mode, limit: size, offset: mode === 'page' ? (page - 1) * size : 0, after, sort, filter, ...(r.search ? { search: r.search } : {}) }
+    const params: ListParams = {
+      mode,
+      limit: size,
+      offset: mode === 'page' ? (page - 1) * size : 0,
+      after,
+      sort,
+      filter,
+      ...(r.search ? { search: r.search } : {}),
+    }
     return { value: params }
   }
   return { '~standard': { version: 1, vendor: 'weft', validate } }
@@ -155,7 +207,13 @@ export interface DbAdapter<T = unknown> {
   source<Row = Record<string, unknown>>(target: T, spec: SourceSpec): ListSource<Row>
 }
 
-const refuse = (what: string) => new StartError('Q002', `the list source refused ${what}`, 'add it to the source\'s `columns`, and to `listInput`', { status: 400 })
+const refuse = (what: string) =>
+  new StartError(
+    'Q002',
+    `the list source refused ${what}`,
+    "add it to the source's `columns`, and to `listInput`",
+    { status: 400 },
+  )
 
 /** A request checked against the source and put in stored names. Throws on any name outside `columns`. */
 export interface Plan {
@@ -175,11 +233,20 @@ export function storedId(spec: SourceSpec): string {
 
 /** Check a request against `spec`, for a source to run. */
 export function plan(spec: SourceSpec, p: ListParams): Plan {
-  const stored = (field: string) => (Object.hasOwn(spec.columns, field) ? spec.columns[field]! : (() => { throw refuse(`\`${field}\``) })())
+  const stored = (field: string) =>
+    Object.hasOwn(spec.columns, field)
+      ? spec.columns[field]!
+      : (() => {
+          throw refuse(`\`${field}\``)
+        })()
   const id = spec.id ?? 'id'
-  const where = Object.keys(p.filter).map(field => ({ column: stored(field), values: [p.filter[field]!].flat() }))
-  if (where.some(w => !w.values.every(scalar))) throw refuse('a filter value that is not a scalar')
-  const searching = p.search ? spec.search ?? [] : []
+  const where = Object.keys(p.filter).map((field) => ({
+    column: stored(field),
+    values: [p.filter[field]!].flat(),
+  }))
+  if (where.some((w) => !w.values.every(scalar)))
+    throw refuse('a filter value that is not a scalar')
+  const searching = p.search ? (spec.search ?? []) : []
   if (p.search && !searching.length) throw refuse('a search')
   return {
     sort: p.sort ? { column: stored(p.sort.field), dir: p.sort.dir, field: p.sort.field } : null,
@@ -192,32 +259,56 @@ export function plan(spec: SourceSpec, p: ListParams): Plan {
 /** A stored row in public names, with only `columns` in it. */
 export const rowOf = <Row = Record<string, unknown>>(spec: SourceSpec) => {
   const pairs = Object.entries(spec.columns)
-  return (row: object) => Object.fromEntries(pairs.filter(([, c]) => c in row).map(([f, c]) => [f, (row as Record<string, unknown>)[c]])) as Row
+  return (row: object) =>
+    Object.fromEntries(
+      pairs.filter(([, c]) => c in row).map(([f, c]) => [f, (row as Record<string, unknown>)[c]]),
+    ) as Row
 }
 
 /** A write in stored names. Refuses anything outside `write`, so a client can't set `role` or move an id. */
-export function written(spec: SourceSpec, data: Record<string, unknown>, creating = false): Record<string, unknown> {
+export function written(
+  spec: SourceSpec,
+  data: Record<string, unknown>,
+  creating = false,
+): Record<string, unknown> {
   const id = spec.id ?? 'id'
-  const allowed = new Set(spec.write ?? Object.keys(spec.columns).filter(f => f !== id))
+  const allowed = new Set(spec.write ?? Object.keys(spec.columns).filter((f) => f !== id))
   if (creating) allowed.add(id)
   const out: Record<string, unknown> = {}
   for (const field of Object.keys(data)) {
-    if (!allowed.has(field) || !Object.hasOwn(spec.columns, field)) throw refuse(`a write to \`${field}\``)
+    if (!allowed.has(field) || !Object.hasOwn(spec.columns, field))
+      throw refuse(`a write to \`${field}\``)
     out[spec.columns[field]!] = data[field]
   }
   return out
 }
 
 /** `rows` are in public names, with one more than `limit` in cursor mode when there is a next page. */
-export function pageOf<R>(rows: R[], p: ListParams, field: { sort?: string | undefined; id: string }, total?: number): ListPage<R> {
+export function pageOf<R>(
+  rows: R[],
+  p: ListParams,
+  field: { sort?: string | undefined; id: string },
+  total?: number,
+): ListPage<R> {
   if (p.mode === 'page') {
     const page = p.offset / p.limit + 1
-    return { items: rows, ...(total === undefined ? {} : { total }), ...(total !== undefined && p.offset + p.limit < total ? { next: page + 1 } : {}), ...(page > 1 ? { prev: page - 1 } : {}) }
+    return {
+      items: rows,
+      ...(total === undefined ? {} : { total }),
+      ...(total !== undefined && p.offset + p.limit < total ? { next: page + 1 } : {}),
+      ...(page > 1 ? { prev: page - 1 } : {}),
+    }
   }
   const more = rows.length > p.limit
   const items = more ? rows.slice(0, p.limit) : rows
   const last = items.at(-1) as R & Record<string, unknown>
-  return { items, ...(total === undefined ? {} : { total }), ...(more ? { next: encodeCursor(field.sort ? last[field.sort] : last[field.id], last[field.id]) } : {}) }
+  return {
+    items,
+    ...(total === undefined ? {} : { total }),
+    ...(more
+      ? { next: encodeCursor(field.sort ? last[field.sort] : last[field.id], last[field.id]) }
+      : {}),
+  }
 }
 
 /** `LIKE` with `!` as the escape: the one character that means the same on SQLite, Postgres and MySQL. */

package/src/listen.ts

@@ -8,17 +8,43 @@ import { StartError } from './data'
 const BEAT = 10_000
 
 /** Listens until the returned `stop`. Run one: two listeners poke twice, which costs a refetch and loses nothing. */
-export async function listen({ changes, bus, say = console.info, beat = BEAT }: { changes: Source; bus: Bus; say?: (line: string) => void; beat?: number }) {
-  if (bus.name === 'memory') throw new StartError('R017', '`weft db listen` publishes to the bus, and the memory bus stops at this process', 'set `bus` in `src/realtime.server.ts`')
+export async function listen({
+  changes,
+  bus,
+  say = console.info,
+  beat = BEAT,
+}: {
+  changes: Source
+  bus: Bus
+  say?: (line: string) => void
+  beat?: number
+}) {
+  if (bus.name === 'memory')
+    throw new StartError(
+      'R017',
+      '`weft db listen` publishes to the bus, and the memory bus stops at this process',
+      'set `bus` in `src/realtime.server.ts`',
+    )
   const how = await changes.probe()
   say(`weft live: ${how.mode} (${how.via})${how.why ? `: ${how.why}` : ''}`)
-  if (how.mode !== 'feed') throw new StartError('R015', `this listener has no real feed${how.why ? `: ${how.why}` : ''}`, how.fix)
+  if (how.mode !== 'feed')
+    throw new StartError(
+      'R015',
+      `this listener has no real feed${how.why ? `: ${how.why}` : ''}`,
+      how.fix,
+    )
   const feed = createFeed(changes, {
-    emit: p => void bus.publish('weft:poke', JSON.stringify(p)).catch(e => say(`weft live: publish failed: ${e?.message ?? e}`)),
-    status: down => say(down ? `weft live: down: ${down}` : 'weft live: back'),
+    emit: (p) =>
+      void bus
+        .publish('weft:poke', JSON.stringify(p))
+        .catch((e) => say(`weft live: publish failed: ${e?.message ?? e}`)),
+    status: (down) => say(down ? `weft live: down: ${down}` : 'weft live: back'),
   })
   await feed.start(how)
-  const beats = setInterval(() => void bus.publish('weft:poke', '{"v":1,"b":1}').catch(() => {}), beat)
+  const beats = setInterval(
+    () => void bus.publish('weft:poke', '{"v":1,"b":1}').catch(() => {}),
+    beat,
+  )
   await bus.publish('weft:poke', '{"v":1,"b":1}')
   return async () => {
     clearInterval(beats)

package/src/live/api.ts

@@ -0,0 +1,18 @@
+import type { LiveApi } from '../data'
+
+// `data.ts` hands these over (`use`). A static import would close a cycle with its `import('./live')`, and the bundler
+// would then keep this chunk, the hub and the split they force in apps that never read `.live`.
+export let cache: LiveApi['cache'],
+  currentScope: LiveApi['currentScope'],
+  fns: LiveApi['fns'],
+  FnError: LiveApi['FnError'],
+  keyOf: LiveApi['keyOf'],
+  net: LiveApi['net'],
+  rt: LiveApi['rt'],
+  runtime: LiveApi['runtime'],
+  skip: LiveApi['skip'],
+  StartError: LiveApi['StartError'],
+  track: LiveApi['track']
+export const use = (api: LiveApi) =>
+  void ({ cache, currentScope, fns, FnError, keyOf, net, rt, runtime, skip, StartError, track } =
+    api)

package/src/live/backoff.ts

@@ -0,0 +1,6 @@
+const BASE = 500
+export const CAP = 30_000
+
+/** Full jitter: anywhere from 0 to 0.5 s, 1 s, 2 s … 30 s. */
+export const backoff = (attempt: number, random = Math.random) =>
+  random() * Math.min(CAP, BASE * 2 ** attempt)

package/src/live/frames.ts

@@ -0,0 +1,42 @@
+import { DEV } from '@weft-js/core'
+import { cache, FnError } from './api'
+import type { Sub } from './sub-types'
+
+export type Row = { 0: number; 1: never; 2: unknown }
+
+export function ack(d: Row, byN: Map<number, Sub>, seeded: () => boolean) {
+  const s = byN.get(d[0])
+  if (!s) return
+  s.tags = d[1]
+  s.error.value = undefined
+  if (DEV && !s.tags.length)
+    console.warn(
+      `weft: W053 \`${s.fn.$id}\` is read with \`.live()\` but declares no \`tags\`: no mutation can ever poke it.\n  fix: add \`tags\` to the query`,
+    )
+  // Data older than the subscription may have missed a write. A page's first connect is covered by its cursor.
+  if (!s.acked && !seeded() && s.tags.length) void cache.invalidate(...s.tags)
+  s.acked = true
+}
+
+export function update(event: string, d: Row, byN: Map<number, Sub>) {
+  if (event === 'm') {
+    const s = byN.get(d[0])
+    if (!s) return
+    if (d[1] !== null) s.cursor = d[1]
+    s.error.value = undefined
+    for (const v of s.views.values())
+      v.box.value = v.fold ? v.fold(v.box.value as never, d[2] as never) : d[2]
+  } else if (event === 'r') {
+    const s = byN.get(d[0])
+    if (!s) return
+    s.cursor = undefined
+    for (const v of s.views.values()) v.box.value = v.initial
+  } else if (event === 'f') {
+    const s = byN.get(d[0])
+    if (s) s.done.value = true
+  } else if (event === 'e') {
+    const s = byN.get(d[0])
+    if (s)
+      s.error.value = new FnError(d[1], (d[1] as { code?: string }).code === 'A002' ? 401 : 500)
+  }
+}

package/src/live/read.ts

@@ -0,0 +1,77 @@
+import {
+  DEV,
+  createRoot,
+  derived,
+  effect,
+  getOwner,
+  onCleanup,
+  state,
+  untrack,
+} from '@weft-js/core'
+import type { Fn } from '../data'
+import { currentScope, rt, skip, StartError } from './api'
+import type { Sub, View } from './sub-types'
+import type { Stream, StreamOptions } from './types'
+
+export function read(
+  fn: Fn,
+  input: unknown,
+  o: StreamOptions<never, unknown> = {},
+  acquire: (fn: Fn, input: unknown) => Sub,
+  held: (s: Sub, keep?: string | number) => () => void,
+): Stream<unknown> {
+  if (!getOwner())
+    throw new StartError(
+      'W051',
+      DEV
+        ? `\`${fn.$id}()\` (a stream) was called outside a component or scope: nothing would close it`
+        : fn.$id,
+      DEV
+        ? 'call it in a component, a `defineState` setup or `createRoot(dispose => …)`'
+        : undefined,
+    )
+  const scope = currentScope()
+  if (scope) {
+    scope.live = true // the server renders `initial`, and the client hydrates to the same
+    return { value: o.initial, status: rt.status, error: undefined }
+  }
+  const view = state<{ s: Sub; v: View } | undefined>(undefined)
+  const fold = o.fold ? String(o.fold) : ''
+  effect(
+    () => {
+      const arg = typeof input === 'function' ? (input as () => unknown)() : input
+      if (arg === skip) return undefined
+      return untrack(() => {
+        const s = acquire(fn, arg)
+        if (o.fold) s.buffer ??= o.buffer ?? 256
+        else if (o.buffer) s.buffer ??= o.buffer
+        let v = s.views.get(fold)
+        if (!v)
+          s.views.set(
+            fold,
+            (v = createRoot(
+              () => ({ fold: o.fold, initial: o.initial, box: state<unknown>(o.initial) }),
+              null,
+            )),
+          )
+        v.fold = o.fold
+        onCleanup(held(s, o.keep))
+        return { s, v }
+      })
+    },
+    (now) => {
+      view.value = now
+    },
+  )
+  const status = derived(() => (view.value?.s.done.value ? 'done' : rt.status.value))
+  return {
+    get value() {
+      const now = view.value
+      return now ? now.v.box.value : o.initial
+    },
+    status,
+    get error() {
+      return view.value?.s.error.value
+    },
+  }
+}

package/src/live/sub-types.ts

@@ -0,0 +1,24 @@
+import type { State } from '@weft-js/core'
+import type { Fn } from '../data'
+
+export interface View {
+  fold?: ((acc: never, m: never) => unknown) | undefined
+  initial: unknown
+  box: State<unknown>
+}
+export interface Sub {
+  n: number
+  key: string
+  fn: Fn
+  input: unknown
+  refs: number
+  timer?: ReturnType<typeof setTimeout> | undefined
+  /** Stream: the last id, sent back on a resume. Query: its tags, from the ack. */
+  cursor?: string | undefined
+  tags: string[]
+  buffer?: number
+  acked: boolean
+  views: Map<string, View>
+  error: State<unknown>
+  done: State<boolean>
+}