@weft-js/start 0.1.0 → 0.1.2

package/src/live/transport.ts

@@ -0,0 +1,86 @@
+import type { Body } from '../hub'
+import { HANDOVER, openLine, type Line } from '../link'
+import { FnError } from './api'
+
+/** How the client reaches `/_weft/rt`: SSE, a shared socket, or a fake under test. */
+export interface Link {
+  /** Resolves when the connection ends. */
+  open(
+    body: Body,
+    frame: (event: string, data: unknown) => void,
+    signal: AbortSignal,
+    alive: () => void,
+  ): Promise<void>
+  change(body: Body): Promise<void>
+}
+
+export function transports(handover: () => void) {
+  const post = (body: Body, signal?: AbortSignal) =>
+    fetch('/_weft/rt', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', accept: 'text/event-stream', 'x-weft': '1' },
+      body: JSON.stringify(body),
+      ...(signal && { signal }),
+    })
+
+  const http: Link = {
+    async open(body, heard, signal, alive) {
+      const res = await post(body, signal)
+      if (!res.ok) {
+        const { e } = await res.json().catch(() => ({ e: {} }))
+        throw new FnError(e, res.status)
+      }
+      const reader = res.body!.getReader()
+      const decoder = new TextDecoder()
+      let buf = ''
+      for (;;) {
+        const { done, value } = await reader.read()
+        if (done) return
+        alive()
+        buf += decoder.decode(value, { stream: true })
+        for (let i; (i = buf.indexOf('\n\n')) >= 0; buf = buf.slice(i + 2)) {
+          if (buf[0] === ':') continue
+          const line = buf.indexOf('\n')
+          heard(buf.slice(7, line), JSON.parse(buf.slice(line + 7, i)))
+        }
+      }
+    },
+    async change(body) {
+      const res = await post(body)
+      if (!res.ok) throw new FnError({}, res.status)
+    },
+  }
+
+  /** A line on the browser's one socket (link.ts): the same events, and `/_weft/rt`'s SSE is for a host with no sockets. */
+  let line: Line | undefined
+  const socket: Link = {
+    open(body, heard, signal, alive) {
+      return new Promise<void>((done, fail) => {
+        const l = (line = openLine(
+          'r',
+          JSON.stringify(body),
+          (text) => {
+            alive()
+            const at = text.indexOf(':'),
+              event = text.slice(0, at)
+            if (event !== 'ping') heard(event, JSON.parse(text.slice(at + 1)))
+          },
+          (code, reason) => {
+            if (line === l) line = undefined
+            if (code === HANDOVER) handover()
+            if (code === 4000 && reason) fail(new FnError(JSON.parse(reason), 429))
+            else done()
+          },
+        ))
+        signal.addEventListener('abort', () => l.close())
+      })
+    },
+    change(body) {
+      if (!line) return Promise.reject(new FnError({}, 503))
+      line.send(JSON.stringify(body))
+      return Promise.resolve()
+    },
+  }
+
+  return { http, socket }
+}

package/src/live/types.ts

@@ -0,0 +1,52 @@
+import type { Derived } from '@weft-js/core'
+import type { Context, LiveOptions, LiveStatus, Skip, StandardSchemaV1 } from '../data'
+import type { Tracked } from '../hub'
+
+export type In<S> = S extends StandardSchemaV1<infer I, unknown> ? I : void
+type Out<S> = S extends StandardSchemaV1<unknown, infer O> ? O : undefined
+
+/** Where a stream stands; `done` is the end of a generator. */
+export type StreamStatus = LiveStatus | 'done'
+
+/** `stream()`: the input, the message schema and the generator. */
+export interface StreamDef<S, M, A = undefined> {
+  input?: S
+  /** Checked in dev and tests (C002), and the contract's `message`. */
+  message?: StandardSchemaV1<unknown, M>
+  auth?: A
+  /** `lastEventId`: the last `tracked` id the client saw, on a resume. Stop when `signal` aborts. */
+  run: (args: {
+    input: Out<S>
+    ctx: Context
+    signal: AbortSignal
+    lastEventId?: string
+  }) => AsyncIterable<M | Tracked<M>>
+  $id?: string
+}
+
+/** `.live()` on a stream: what the value starts as, and how messages fold into it. */
+export interface StreamOptions<M, T> extends LiveOptions {
+  /** Keep every message: `fold(acc, message)`. Its state lives in the cache, so a remount finds it. */
+  fold?: (acc: T, message: M) => T
+  initial?: T
+  /** Messages the server holds for a slow client. A fold defaults to 256; without one, the latest wins. */
+  buffer?: number
+}
+
+/** A stream as a page reads it. */
+export interface Stream<T> {
+  /** The latest message, or the fold. */
+  readonly value: T
+  readonly status: Derived<StreamStatus>
+  readonly error: unknown
+}
+
+/** What `stream()` returns. */
+export interface StreamFn<I, M> {
+  (input: Arg<I>): Stream<M | undefined>
+  <T>(input: Arg<I>, options: StreamOptions<M, T> & { initial: T }): Stream<T>
+  (input: Arg<I>, options: StreamOptions<M, M>): Stream<M | undefined>
+  readonly kind: 'stream'
+  readonly $id: string
+}
+type Arg<I> = I | (() => I | Skip)

package/src/live-fake.ts

@@ -15,7 +15,17 @@ export async function change(body: Body) {
 }
 
 /** A connection to the real hub in this process. */
-export async function open(body: Body, frame: (event: string, data: unknown) => void, signal: AbortSignal, up: () => void, subs: Map<string, { fn: Fn; input: unknown }>, closing: (close: () => unknown) => void) {
+export async function open(
+  body: Body,
+  frame: (event: string, data: unknown) => void,
+  signal: AbortSignal,
+  hooks: {
+    up: () => void
+    subs: Map<string, { fn: Fn; input: unknown }>
+    closing: (close: () => unknown) => void
+  },
+) {
+  const { up, subs, closing } = hooks
   const n = net()!
   const [{ hub, resetHub }, exec] = await Promise.all([import('./hub'), loadExec()])
   if (!n.online()) throw Object.assign(new Error('offline'), { name: 'OfflineError' })
@@ -25,15 +35,20 @@ export async function open(body: Body, frame: (event: string, data: unknown) =>
   const request = new Request('http://localhost/_weft/rt', { method: 'POST' })
   return new Promise<void>((done, fail) => {
     let conn: Parameters<typeof h.close>[0] | undefined
-    const sink = { write: (e: string, d: string) => frame(e, JSON.parse(d)), backlog: () => 0, close: () => done() }
+    const sink = {
+      write: (e: string, d: string) => frame(e, JSON.parse(d)),
+      backlog: () => 0,
+      close: () => done(),
+    }
     n.rt = {
       push: (id, msg) => h.push(id, msg),
-      poke: tags => h.poke(tags),
+      poke: (tags) => h.poke(tags),
       drop: () => conn && h.close(conn),
-      subscriptions: () => [...subs.values()].map(s => ({ kind: s.fn.kind, id: s.fn.$id, input: s.input })),
+      subscriptions: () =>
+        [...subs.values()].map((s) => ({ kind: s.fn.kind, id: s.fn.$id, input: s.input })),
     }
     signal.addEventListener('abort', () => (conn ? h.close(conn) : done()))
-    h.connect(request, fakeScope(exec, n, request), body, sink).then(c => {
+    h.connect(request, fakeScope(exec, n, request), body, sink).then((c) => {
       conn = c
       if (signal.aborted) h.close(c)
       up()

package/src/live-target.mjs

@@ -4,14 +4,21 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 
-const LISTENER = 'run `weft db listen` on any always-on host (a VPS, Fly, Railway), publishing into a shared bus, and set `dbChanges(db, tables, { listener: \'external\' })`'
-const SERVER = 'deploy to a server preset (`node_server`, `bun`, `deno_server`, or a container on Fly, Railway or Render)'
+const LISTENER =
+  "run `weft db listen` on any always-on host (a VPS, Fly, Railway), publishing into a shared bus, and set `dbChanges(db, tables, { listener: 'external' })`"
+const SERVER =
+  'deploy to a server preset (`node_server`, `bun`, `deno_server`, or a container on Fly, Railway or Render)'
 const POLLED = 'or poll the query yourself by reloading: `.live()` still updates on mutations'
 
 /** Presets that give each request its own short-lived process. */
 const FUNCTIONS = [
-  [/^vercel/, 'Vercel Functions'], [/^netlify/, 'Netlify Functions'], [/^aws[-_]lambda/, 'AWS Lambda'], [/^azure/, 'Azure Functions'],
-  [/^firebase/, 'Firebase Functions'], [/^cloudflare/, 'Cloudflare Workers'], [/^deno[-_]deploy/, 'Deno Deploy'],
+  [/^vercel/, 'Vercel Functions'],
+  [/^netlify/, 'Netlify Functions'],
+  [/^aws[-_]lambda/, 'AWS Lambda'],
+  [/^azure/, 'Azure Functions'],
+  [/^firebase/, 'Firebase Functions'],
+  [/^cloudflare/, 'Cloudflare Workers'],
+  [/^deno[-_]deploy/, 'Deno Deploy'],
 ]
 
 /**
@@ -20,32 +27,41 @@ const FUNCTIONS = [
  */
 export function liveTarget(preset = 'node') {
   const hit = FUNCTIONS.find(([re]) => re.test(preset))
-  return hit ? { preset, held: false, host: hit[1] } : { preset, held: true, host: 'a long-running server' }
+  return hit
+    ? { preset, held: false, host: hit[1] }
+    : { preset, held: true, host: 'a long-running server' }
 }
 
+/** Whether a deploy can hold a browser's socket: a long-running server, a Durable Object, or Deno's upgraded request. */
+export const holdsSockets = (preset = 'node') =>
+  liveTarget(preset).held || /^(cloudflare[-_]durable|deno[-_]deploy)/.test(preset)
+
 const SKIP = new Set(['node_modules', '.weft', '.output', 'dist'])
 
 /** `live: { required: true }` on a query, and `.live(input, { required: true })` in a component, with where. */
 export function scanRequired(root) {
   const out = []
-  const walk = dir => {
+  const walk = (dir) => {
     for (const d of readdirSync(dir, { withFileTypes: true })) {
       const f = join(dir, d.name)
-      if (d.isDirectory()) { if (!SKIP.has(d.name)) walk(f) } else if (/\.[cm]?[jt]sx?$/.test(d.name) && !/\.test\./.test(d.name)) read(f)
+      if (d.isDirectory()) {
+        if (!SKIP.has(d.name)) walk(f)
+      } else if (/\.[cm]?[jt]sx?$/.test(d.name) && !/\.test\./.test(d.name)) read(f)
     }
   }
-  const read = file => {
+  const read = (file) => {
     const text = readFileSync(file, 'utf8')
     if (!/required:\s*true/.test(text)) return
     for (const m of text.matchAll(/\blive:\s*\{[^}]*required:\s*true/g)) {
       const name = [...text.slice(0, m.index).matchAll(/\b(\w+)\s*=\s*query\s*[(<]/g)].at(-1)?.[1]
       if (name) out.push({ name, file: file.slice(root.length + 1) })
     }
-    for (const m of text.matchAll(/\b(\w+)\.live\(([^;\n]*?)\brequired:\s*true/g)) out.push({ name: m[1], file: file.slice(root.length + 1) })
+    for (const m of text.matchAll(/\b(\w+)\.live\(([^;\n]*?)\brequired:\s*true/g))
+      out.push({ name: m[1], file: file.slice(root.length + 1) })
   }
   const src = join(root, 'src')
   if (existsSync(src)) walk(src)
-  return [...new Map(out.map(r => [r.name, r])).values()]
+  return [...new Map(out.map((r) => [r.name, r])).values()]
 }
 
 /**
@@ -54,14 +70,20 @@ export function scanRequired(root) {
  */
 export function livePlan({ preset, source, required = [] }) {
   const target = liveTarget(preset)
-  const names = required.map(r => `\`${r.name}\``).join(', ')
+  const names = required.map((r) => `\`${r.name}\``).join(', ')
   const diagnostics = []
   const options = target.held ? [] : [LISTENER, SERVER]
   let mode, says
   if (!source) {
     mode = 'app'
-    says = 'Mutations update `.live()` queries. Writes from outside the app do not: nothing listens to the database.'
-    if (required.length) diagnostics.push({ code: 'R013', severity: 'error', why: `${names} require${required.length > 1 ? '' : 's'} a live feed, and \`src/realtime.server.ts\` sets no \`changes\`. Add \`changes: dbChanges(db, [tables])\`, or drop \`required\`.` })
+    says =
+      'Mutations update `.live()` queries. Writes from outside the app do not: nothing listens to the database.'
+    if (required.length)
+      diagnostics.push({
+        code: 'R013',
+        severity: 'error',
+        why: `${names} require${required.length > 1 ? '' : 's'} a live feed, and \`src/realtime.server.ts\` sets no \`changes\`. Add \`changes: dbChanges(db, [tables])\`, or drop \`required\`.`,
+      })
   } else if (source.external) {
     mode = 'external'
     says = `A separate listener reports writes to ${source.tables.join(', ')} through the bus. It is yours to keep running; \`.live()\` shows \`reconnecting\` when it goes quiet.`
@@ -71,40 +93,86 @@ export function livePlan({ preset, source, required = [] }) {
   } else {
     mode = 'off'
     says = `${target.host} ends a process with its request, so nothing can hold a connection to ${source.name}: mutations update \`.live()\`, and writes from outside the app do not. \`.live()\` shows \`degraded\`.`
-    if (required.length) diagnostics.push({ code: 'R013', severity: 'error', why: `${names} require${required.length > 1 ? '' : 's'} a live feed, and \`${target.preset}\` can't hold one: ${target.host} ends a process with its request. Either ${LISTENER}, or ${SERVER}, or drop \`required\`.` })
-    else diagnostics.push({ code: 'R014', severity: 'warning', why: `\`changes\` needs a process that stays up, and on \`${target.preset}\` none does: writes from outside the app won't reach \`.live()\`. Either ${LISTENER}, or ${SERVER}, ${POLLED}.` })
+    if (required.length)
+      diagnostics.push({
+        code: 'R013',
+        severity: 'error',
+        why: `${names} require${required.length > 1 ? '' : 's'} a live feed, and \`${target.preset}\` can't hold one: ${target.host} ends a process with its request. Either ${LISTENER}, or ${SERVER}, or drop \`required\`.`,
+      })
+    else
+      diagnostics.push({
+        code: 'R014',
+        severity: 'warning',
+        why: `\`changes\` needs a process that stays up, and on \`${target.preset}\` none does: writes from outside the app won't reach \`.live()\`. Either ${LISTENER}, or ${SERVER}, ${POLLED}.`,
+      })
+  }
+  return {
+    preset: target.preset,
+    held: target.held,
+    host: target.host,
+    mode,
+    says,
+    required: required.map((r) => r.name),
+    options,
+    diagnostics,
   }
-  return { preset: target.preset, held: target.held, host: target.host, mode, says, required: required.map(r => r.name), options, diagnostics }
 }
 
 // ---- `verify` ---------------------------------------------------------------------------------------------------------
 
 const PRODUCTION = /(^|[.\-_])(prod|production|live|www|main|master)([.\-_]|$)/i
-const NOT_PRODUCTION = /(^|[.\-_])(staging|stage|stg|dev|develop|development|test|testing|qa|sandbox|preview|uat|demo)([.\-_]|$)|^localhost$|^127\.|^\[?::1\]?$/i
+const NOT_PRODUCTION =
+  /(^|[.\-_])(staging|stage|stg|dev|develop|development|test|testing|qa|sandbox|preview|uat|demo)([.\-_]|$)|^localhost$|^127\.|^\[?::1\]?$/i
 
-const hostOf = url => { try { return new URL(url).hostname } catch { return url } }
-const dbNameOf = url => { try { return new URL(url).pathname.slice(1) } catch { return '' } }
+const hostOf = (url) => {
+  try {
+    return new URL(url).hostname
+  } catch {
+    return url
+  }
+}
+const dbNameOf = (url) => {
+  try {
+    return new URL(url).pathname.slice(1)
+  } catch {
+    return ''
+  }
+}
 
-const HOWTO = 'Set `WEFT_STAGING_URL` to a running staging app, `STAGING_DATABASE_URL` to its database, or both for the whole chain.'
+const HOWTO =
+  'Set `WEFT_STAGING_URL` to a running staging app, `STAGING_DATABASE_URL` to its database, or both for the whole chain.'
 
 /**
  * Where a `verify` points, from the query's declaration, `live.targets` in weft.config.ts and the environment.
  * @returns {{ name: string, url?: string, db?: string, marked: boolean } | { missing: string }}
  */
 export function resolveTarget(verify, { targets = {}, env = process.env } = {}) {
-  if (typeof verify === 'object' && verify.target !== undefined) return resolveTarget(verify.target, { targets, env })
+  if (typeof verify === 'object' && verify.target !== undefined)
+    return resolveTarget(verify.target, { targets, env })
   if (verify === true) {
-    const url = env.WEFT_STAGING_URL, db = env.STAGING_DATABASE_URL
-    return url || db ? { name: 'staging', url, db, marked: false } : { missing: `\`verify: true\` found neither \`WEFT_STAGING_URL\` nor \`STAGING_DATABASE_URL\`. ${HOWTO}` }
+    const url = env.WEFT_STAGING_URL,
+      db = env.STAGING_DATABASE_URL
+    return url || db
+      ? { name: 'staging', url, db, marked: false }
+      : {
+          missing: `\`verify: true\` found neither \`WEFT_STAGING_URL\` nor \`STAGING_DATABASE_URL\`. ${HOWTO}`,
+        }
   }
   if (typeof verify === 'string') {
     const t = targets[verify]
-    if (!t) return { missing: `\`verify: '${verify}'\` names no target. Add it to weft.config.ts: \`live: { targets: { ${verify}: { url: 'https://…', db: 'STAGING_DATABASE_URL', production: false } } }\`` }
+    if (!t)
+      return {
+        missing: `\`verify: '${verify}'\` names no target. Add it to weft.config.ts: \`live: { targets: { ${verify}: { url: 'https://…', db: 'STAGING_DATABASE_URL', production: false } } }\``,
+      }
     const db = t.db && (t.db.includes('://') ? t.db : env[t.db])
-    if (t.db && !db) return { missing: `target \`${verify}\` reads its database from \`${t.db}\`, which isn't set on this machine.` }
+    if (t.db && !db)
+      return {
+        missing: `target \`${verify}\` reads its database from \`${t.db}\`, which isn't set on this machine.`,
+      }
     return { name: verify, url: t.url, db, marked: t.production === false }
   }
-  if (!verify.url && !verify.db) return { missing: `\`verify\` got an empty target (is its env var set?). ${HOWTO}` }
+  if (!verify.url && !verify.db)
+    return { missing: `\`verify\` got an empty target (is its env var set?). ${HOWTO}` }
   return { name: 'inline', url: verify.url, db: verify.db, marked: false }
 }
 
@@ -112,12 +180,18 @@ export function resolveTarget(verify, { targets = {}, env = process.env } = {})
 export function refusal(target, { targets = {} } = {}) {
   const hosts = [target.url && hostOf(target.url), target.db && hostOf(target.db)].filter(Boolean)
   const names = [target.name, ...hosts, ...(target.db ? [dbNameOf(target.db)] : [])]
-  const said = names.find(n => PRODUCTION.test(n))
+  const said = names.find((n) => PRODUCTION.test(n))
   if (said) return `\`${said}\` looks like production: \`verify\` writes rows, and won't go near it`
-  if (target.name !== 'inline' && target.name !== 'staging' && targets[target.name]?.production !== false) return `target \`${target.name}\` isn't marked: add \`production: false\` to it in weft.config.ts`
+  if (
+    target.name !== 'inline' &&
+    target.name !== 'staging' &&
+    targets[target.name]?.production !== false
+  )
+    return `target \`${target.name}\` isn't marked: add \`production: false\` to it in weft.config.ts`
   if (target.marked) return
-  const unsure = hosts.find(h => !NOT_PRODUCTION.test(h))
-  if (unsure) return `nothing says \`${unsure}\` isn't production. Name it in weft.config.ts: \`live: { targets: { staging: { db: 'STAGING_DATABASE_URL', production: false } } }\`, and use \`verify: 'staging'\``
+  const unsure = hosts.find((h) => !NOT_PRODUCTION.test(h))
+  if (unsure)
+    return `nothing says \`${unsure}\` isn't production. Name it in weft.config.ts: \`live: { targets: { staging: { db: 'STAGING_DATABASE_URL', production: false } } }\`, and use \`verify: 'staging'\``
 }
 
 const PASSWORD = /[a-z][a-z0-9+.-]*:\/\/[^\s'"`/:@]+:[^\s'"`/@]+@/i
@@ -125,20 +199,24 @@ const PASSWORD = /[a-z][a-z0-9+.-]*:\/\/[^\s'"`/:@]+:[^\s'"`/@]+@/i
 /** R020: a connection string with a password, written into source. An env var's value never reaches this. */
 export function literalSecrets(root) {
   const out = []
-  const look = file => {
+  const look = (file) => {
     const text = readFileSync(file, 'utf8')
     if (!/\b(verify|targets)\b/.test(text)) return
     text.split('\n').forEach((line, i) => {
-      if (PASSWORD.test(line) && /\b(db|url|verify)\b/.test(line)) out.push({ file: file.slice(root.length + 1), line: i + 1 })
+      if (PASSWORD.test(line) && /\b(db|url|verify)\b/.test(line))
+        out.push({ file: file.slice(root.length + 1), line: i + 1 })
     })
   }
-  const walk = dir => {
+  const walk = (dir) => {
     for (const d of readdirSync(dir, { withFileTypes: true })) {
       const f = join(dir, d.name)
-      if (d.isDirectory()) { if (!SKIP.has(d.name)) walk(f) } else if (/\.[cm]?[jt]sx?$/.test(d.name)) look(f)
+      if (d.isDirectory()) {
+        if (!SKIP.has(d.name)) walk(f)
+      } else if (/\.[cm]?[jt]sx?$/.test(d.name)) look(f)
     }
   }
   if (existsSync(join(root, 'src'))) walk(join(root, 'src'))
-  for (const f of ['weft.config.ts', 'weft.config.js', 'weft.config.mjs']) if (existsSync(join(root, f))) look(join(root, f))
+  for (const f of ['weft.config.ts', 'weft.config.js', 'weft.config.mjs'])
+    if (existsSync(join(root, f))) look(join(root, f))
   return out
 }