@weft-js/start 0.1.0 → 0.1.2

package/src/data/mutation.ts

@@ -0,0 +1,138 @@
+import { DEV, flush, untrack, type State } from '@weft-js/core'
+import { client, peers } from '../router'
+import { entries, entry, setBase, staleTags, relieve, cache, type Entry, type Layer } from './cache'
+import { fnOf, fns, go, runtime, server } from './foundation'
+import { FnError } from './primitives'
+import { transport } from './transport'
+import type { Answer, Fn, OptimisticCache } from './types'
+
+export async function mutate(
+  fn: Fn,
+  input: unknown,
+  calls: State<number>,
+  error: State<unknown>,
+  form?: true | FormData,
+): Promise<unknown> {
+  const scope = server()
+  if (scope) return (await runtime.exec!.runMutation(scope, fn, input, [], !!form)).v
+  const m = ++callId
+  const touched = new Set<Entry>()
+  let overlap = 0
+  untrack(() => calls.value++)
+  const drop = (e: Entry) => {
+    e.layers.value = e.layers.value.filter((l) => l.m !== m)
+  }
+  const wait = (e: Entry) => {
+    e.layers.value = e.layers.value.map((l) => (l.m === m ? { ...l, waiting: true } : l))
+  }
+  try {
+    if (fn.def.optimistic) untrack(() => fn.def.optimistic!({ input }, overlay(m, touched)))
+    const refresh = [...entries.values()]
+      .filter((e) => e.readers > 0)
+      .map((e) => [e.id, e.input] as [string, unknown])
+    if (!open++) run++
+    overlap = run
+    const a = await settled(() => transport().mutate(fn.$id, input, refresh, form))
+    if (a.x) client.sessionChanged?.()
+    const out = applyResult({ fn, a, touched, m, overlap, error, drop, wait })
+    if (a.t?.length) peers?.postMessage(a.t)
+    if (a.x) peers?.postMessage(0)
+    if (a.r !== undefined) {
+      if (a.x) location.assign(a.r)
+      else go(a.r)
+    }
+    return out
+  } catch (err) {
+    untrack(() => {
+      for (const e of touched) {
+        drop(e) // only this call's prediction goes
+        if (overlap && (!(err instanceof FnError) || err.status >= 500)) e.held = true // the reply was lost, not the write: it may have landed
+      }
+      flush() // readers roll back now, not when the read below answers
+      for (const e of touched) relieve(e)
+      error.value = err
+    })
+    throw err
+  } finally {
+    untrack(() => calls.value--)
+  }
+}
+function applyResult(o: {
+  fn: Fn
+  a: Answer
+  touched: Set<Entry>
+  m: number
+  overlap: number
+  error: State<unknown>
+  drop: (e: Entry) => void
+  wait: (e: Entry) => void
+}) {
+  const { fn, a, touched, m, overlap, error, drop, wait } = o
+  let out: unknown
+  untrack(() => {
+    const refreshed = new Set<string>()
+    const seen: Entry[] = []
+    for (const w of a.c ?? []) {
+      const e = entry(fns.get(w[0]) ?? ({ $id: w[0] } as Fn), w[1])
+      refreshed.add(e.key)
+      seen.push(e)
+      // Replies don't say which came first, and one taken in arrival order can put back what a later call changed: where
+      // calls overlap on an entry its layers stay, in order, and it reads once the last has answered.
+      if (e.held || e.run === overlap || e.layers.value.some((l) => l.m !== m)) {
+        e.held = true
+        wait(e)
+      } else {
+        setBase(e, w[2], w[3])
+        drop(e)
+        e.run = overlap
+      }
+    }
+    for (const e of touched) {
+      if (refreshed.has(e.key)) continue
+      // S011: the server sent no fresh value for an entry this call predicted. Keep the layer until the entry's
+      // next value (refetched now) instead of flashing back to the old one.
+      if (DEV && !e.tags.some((t) => a.t?.includes(t)))
+        console.warn(
+          `weft: S011 \`${fn.$id}\`'s optimistic updated \`${e.key}\` (tags ${JSON.stringify(e.tags)}), but its invalidated tags ${JSON.stringify(a.t ?? [])} don't cover it: the prediction had no fresh value to land on.\n  fix: add one of its tags to \`invalidates\``,
+        )
+      wait(e)
+      e.held = true
+    }
+    staleTags(a.t ?? [], refreshed)
+    for (const e of seen) relieve(e)
+    for (const e of touched) relieve(e)
+    error.value = undefined
+    out = a.v
+  })
+  return out
+}
+
+let callId = 0
+/** Calls in flight, and which unbroken run of overlapping calls they belong to. */
+let open = 0
+let run = 0
+const settled = async <T>(call: () => Promise<T>) => {
+  try {
+    return await call()
+  } finally {
+    open--
+  }
+}
+
+/** The `cache` an `optimistic` gets: `update` and `set` add this call's layers instead of writing the base. */
+function overlay(m: number, touched: Set<Entry>): OptimisticCache {
+  const push = (q: unknown, input: unknown, apply: Layer['apply']) => {
+    const e = entry(fnOf(q), input)
+    touched.add(e)
+    e.layers.value = [...e.layers.value, { m, apply }]
+  }
+  return {
+    ...cache,
+    update: (q, input, recipe) => push(q, input, recipe as Layer['apply']),
+    set: (q, input, value) => push(q, input, () => value),
+  }
+}
+
+export function resetMutation() {
+  callId = open = 0
+}

package/src/data/primitives.ts

@@ -0,0 +1,135 @@
+import type { SchemaIssue } from './types'
+
+/** A diagnostic thrown by @weft-js/start: `code` (Q001…) and a fix in the message, like Weft's StateError. */
+export class StartError extends Error {
+  /** The HTTP status, when `extra` sets one. */
+  declare status?: number
+  /** Field by field, when `extra` sets them. */
+  declare issues?: SchemaIssue[]
+  /** What a declared error carries. */
+  declare data?: unknown
+  /** `raise`: this is a failure the function declares, so its message reaches the client. */
+  declare typed?: boolean
+  constructor(
+    public code: string,
+    message: string,
+    fix?: string,
+    public extra: Record<string, unknown> = {},
+  ) {
+    super(`${code}: ${message}${fix ? `\n  fix: ${fix}` : ''}`)
+    Object.assign(this, extra)
+  }
+}
+
+/** A failed server function call, as the client sees it. */
+export class FnError extends Error {
+  code?: string
+  status: number
+  issues?: SchemaIssue[]
+  /** What a declared error (`errors`) carries. */
+  data?: unknown
+  constructor(
+    e: { message?: string; code?: string; issues?: SchemaIssue[] | undefined; data?: unknown },
+    status: number,
+  ) {
+    super(e.message ?? `server function failed (${status})`)
+    this.status = status
+    Object.assign(this, { code: e.code, issues: e.issues, data: e.data })
+  }
+}
+
+declare const redirectBrand: unique symbol
+/** What `redirect()` throws: a loader or a function's way to send the page elsewhere. */
+export interface Redirect {
+  readonly isRedirect: true
+  readonly href: string
+  readonly status: number
+  readonly [redirectBrand]?: true
+}
+
+/**
+ * Send the request elsewhere: in `load` (a page answers 307 with `location`, client navigation follows) or in a
+ * `run` (the client router navigates). It throws, so `(await db.get(id)) ?? redirect('/todos')` types as the row.
+ */
+export function redirect(href: string, status: 301 | 302 | 303 | 307 | 308 = 307): never {
+  // oxlint-disable-next-line typescript/only-throw-error -- control flow, not a failure: a stack costs and nothing reads it
+  throw { isRedirect: true, href, status } as Redirect
+}
+
+/** Whether a thrown value is a `redirect()`. */
+export const isRedirect = (v: unknown): v is Redirect =>
+  !!v && typeof v === 'object' && (v as Partial<Redirect>).isRedirect === true
+
+/**
+ * Fail with an error the function declares in `errors`. The client sees it as `FnError.code` and `.data`, whether `run`
+ * or a Rust `impl` raised it.
+ */
+export function raise(code: string, data?: unknown): never {
+  throw new StartError(code, `failed: ${code}`, undefined, { status: 400, data, typed: true })
+}
+
+/** Refuse a value the schema can't judge (`email` is taken): `<Form>` shows it next to the field, as a schema issue. */
+export function invalid(fields: Record<string, string>): never {
+  throw new StartError('Q002', Object.keys(fields).join(', '), undefined, {
+    status: 422,
+    issues: Object.entries(fields).map(([k, message]) => ({ message, path: k.split('.') })),
+  })
+}
+
+/** Issues as a form shows them: by field (`a.b`), and the ones that name no field. */
+export function fieldsOf(issues: readonly SchemaIssue[] = []) {
+  const errors: Record<string, string> = {}
+  let message: string | undefined
+  for (const i of issues) {
+    const key = i.path?.map((p) => (typeof p === 'object' ? p.key : p)).join('.')
+    if (key) errors[key] ??= i.message
+    else message ??= i.message
+  }
+  return { errors, message }
+}
+
+type Tree = Record<string, unknown>
+
+const UNSAFE = new Set(['__proto__', 'constructor', 'prototype'])
+
+/** A form's fields as a mutation's input, on both sides (research 29 §5): `a.b` nests, `x[]` and repeats are arrays. */
+export function decodeForm(data: FormData): Record<string, unknown> {
+  const out: Tree = {}
+  for (const [name, value] of data) {
+    if (name[0] === '$' || (typeof value !== 'string' && !value.size)) continue // `$fn`; a file input left empty
+    const list = name.endsWith('[]')
+    const path = (list ? name.slice(0, -2) : name).split('.')
+    if (path.some((p) => UNSAFE.has(p))) continue
+    let at = out
+    for (const p of path.slice(0, -1)) {
+      const next = at[p]
+      at = (next && typeof next === 'object' ? next : (at[p] = {})) as Tree
+    }
+    const k = path.at(-1)!
+    // Own keys only: a field named `toString` is a field, not the method every object inherits.
+    const had = Object.hasOwn(at, k)
+    if (list) ((had ? at[k] : (at[k] = [])) as unknown[]).push(value)
+    else if (had) at[k] = [at[k]].flat().concat(value)
+    else at[k] = value
+  }
+  return out
+}
+
+// ---- keys -------------------------------------------------------------------------------------------------------
+
+/** JSON with sorted object keys: the same input gives the same key on both sides (no input: `''`; JSON sends null). */
+export function stable(v: unknown): string {
+  if (v == null) return ''
+  return JSON.stringify(v, (_, x: Record<string, unknown>) =>
+    x && typeof x === 'object' && !Array.isArray(x)
+      ? Object.fromEntries(
+          Object.keys(x)
+            .sort()
+            .map((k) => [k, x[k]]),
+        )
+      : x,
+  )
+}
+
+/** The cache key of one call: the function's id and its input in a stable order. */
+export const keyOf = (id: string, input: unknown) => `${id}:${stable(input)}`

package/src/data/query.ts

@@ -0,0 +1,106 @@
+import { DEV, effect, getOwner, onCleanup, resource, untrack, type Resource } from '@weft-js/core'
+import { fill, mask } from '@weft-js/core/shape'
+import { entries, entry, fresh, lastSeen, load, predicted } from './cache'
+import { rt, runtime, server, skip, net } from './foundation'
+import { liveApi } from './live-api'
+import { keyOf, StartError } from './primitives'
+import { track } from './transport'
+import type { Fn, LiveOptions, LiveQuery } from './types'
+
+export function fetchQuery(fn: Fn, input: unknown): Promise<unknown> {
+  const scope = server()
+  if (scope) return runtime.exec!.fetchQuery(scope, fn, input).then((e) => e.v)
+  if (runtime.exec && !net())
+    return runtime.exec
+      .fetchQuery(runtime.exec.createScope(new Request('http://localhost/')), fn, input)
+      .then((e) => e.v)
+  const e = entry(fn, input)
+  return untrack(() => fresh(e)) ? Promise.resolve(untrack(() => e.value.value)) : load(e)
+}
+
+export function use(fn: Fn, input: unknown): Resource<unknown> {
+  if (!getOwner())
+    throw DEV
+      ? new StartError(
+          'Q001',
+          `\`${fn.$id}()\` (a live query) was called outside a component or scope`,
+          `\`await ${name(fn)}.fetch(input)\` in \`load\`, handlers and server code`,
+        )
+      : new StartError('Q001', fn.$id)
+  const read = () => (typeof input === 'function' ? (input as () => unknown)() : input)
+  return resource(
+    () => {
+      const arg = read()
+      if (arg === skip) return undefined
+      const scope = server()
+      if (scope) return runtime.exec!.readQuery(scope, fn, arg)
+      const e = entry(fn, arg)
+      e.readers++
+      onCleanup(() => void e.readers--)
+      const v = e.value.value // tracked: a new base or layer re-runs this, and the resource settles to it in place
+      if (fresh(e)) return v
+      if (e.has.value && predicted(e)) {
+        e.held = true // the prediction shows now, and a read waits for the calls behind it
+        return v
+      }
+      return e.has.value ? load(e).catch(() => untrack(() => e.value.value)) : load(e) // a failed refetch leaves what's on screen
+    },
+    {
+      data: false,
+      shape: {
+        of: fn,
+        read() {
+          const arg = read()
+          return arg === skip ? undefined : shapeOf(fn, arg)
+        },
+      },
+    },
+  )
+}
+
+/** Research 31 §2: this entry's value or the query's last seen, masked; else the declared shape. */
+export function shapeOf(fn: Fn, input: unknown): unknown {
+  const limit: number | undefined = (input as { limit?: number } | undefined)?.limit
+  const here = entries.get(keyOf(fn.$id, input))
+  const e = server()
+    ? undefined
+    : here && untrack(() => here.has.value)
+      ? here
+      : lastSeen.get(fn.$id)
+  if (e)
+    return mask(
+      untrack(() => e.value.value),
+      limit,
+    )
+  const tree = runtime.exec ? runtime.exec.shapeOf(fn) : fn.def.shape
+  return tree === undefined ? undefined : fill(tree, limit)
+}
+
+/** `q()` plus a subscription: its tags come from the server, and a poke is a local `cache.invalidate`. */
+export function liveQuery(fn: Fn, input: unknown, options?: LiveOptions): LiveQuery<unknown> {
+  const r = use(fn, input)
+  const scope = server()
+  if (scope) scope.live = true
+  else
+    effect(
+      () => {
+        const arg = typeof input === 'function' ? (input as () => unknown)() : input
+        if (arg === skip) return
+        let gone = false,
+          stop: (() => void) | undefined
+        const held = import('../live').then((m) => {
+          m.use(liveApi)
+          if (!gone) stop = m.hold(fn, arg, options)
+        })
+        void track(held)
+        onCleanup(() => {
+          gone = true
+          stop?.()
+        })
+      },
+      () => {},
+    )
+  return Object.assign(r, { live: rt.status, liveMode: rt.mode })
+}
+
+const name = (fn: Fn) => fn.$id.replace(/\..*$/, '')

package/src/data/transport.ts

@@ -0,0 +1,121 @@
+import type * as Exec from '../exec'
+import type { Scope } from '../exec'
+import { fns, net, runtime } from './foundation'
+import { FnError, isRedirect, stable, StartError } from './primitives'
+import type { Answer, Fn, NetControl, Transport } from './types'
+
+export function transport(): Transport {
+  if (runtime.transport) return runtime.transport
+  if (net()) return inProcess
+  return http
+}
+
+const answer = async (res: Response): Promise<Answer> => {
+  const body = await res
+    .json()
+    .catch(() => ({ e: { message: `server function answered ${res.status}` } }))
+  if (body.e) throw new FnError(body.e, res.status)
+  return body
+}
+
+/** The browser's: GET for queries, POST + JSON + `x-weft` for mutations (research 27 §3). */
+export const http: Transport = {
+  query: (id, input) =>
+    fetch(`/_weft/fn/${id}${input == null ? '' : `?i=${encodeURIComponent(stable(input))}`}`, {
+      headers: { accept: 'application/json' },
+    }).then(answer),
+  mutate(id, input, f, form) {
+    const headers: Record<string, string> = {
+      accept: 'application/json',
+      'x-weft': '1',
+      ...(runtime.conn && { 'x-weft-conn': runtime.conn }),
+    }
+    if (form instanceof FormData) form.set('$r', JSON.stringify(f))
+    else headers['content-type'] = 'application/json'
+    return fetch(`/_weft/fn/${id}`, {
+      method: 'POST',
+      headers,
+      body:
+        form instanceof FormData ? form : JSON.stringify({ i: input, f, ...(form && { c: 1 }) }),
+    }).then(answer)
+  },
+}
+
+/**
+ * @weft-js/core/test's fake transport: the server's executor in process, with the controls @weft-js/core/test's `net` sets (latency,
+ * failures, replaced functions, offline), and a JSON round trip both ways so values arrive as they would over HTTP.
+ */
+export const fakeScope = (exec: typeof Exec, n: NetControl, request: Request) =>
+  exec.createScope(request, {
+    context: () => n.ctx ?? {},
+    handlers: n.handlers,
+    dev: true,
+    extensions: n.extensions,
+    onDiagnostic: (d) =>
+      console.warn(`weft: ${d.message.startsWith(d.code) ? '' : d.code + ' '}${d.message}`),
+  })
+
+type Call = (exec: typeof Exec, scope: Scope, fn: Fn) => Promise<Answer>
+
+const inProcess: Transport = {
+  query: (id, input) =>
+    fake(id, 'query', input, (exec, scope, fn) =>
+      exec.fetchQuery(scope, fn, input).then((e) => ({ v: e.v, t: e.tags })),
+    ),
+  mutate: (id, input, f, form) =>
+    fake(id, 'mutation', input, (exec, scope, fn) => exec.runMutation(scope, fn, input, f, !!form)),
+}
+
+function fake(id: string, kind: string, input: unknown, call: Call): Promise<Answer> {
+  return track(fakeCall(net()!, id, kind, input, call))
+}
+
+/** `net.settle()` waits for `p`. */
+export function track<T>(p: Promise<T>): Promise<T> {
+  const n = net()
+  if (!n) return p
+  n.inflight.add(p)
+  const over = () => void n.inflight.delete(p)
+  p.then(over, over)
+  return p
+}
+
+async function fakeCall(
+  n: NetControl,
+  id: string,
+  kind: string,
+  input: unknown,
+  call: Call,
+): Promise<Answer> {
+  n.log.push({ id, kind, input })
+  const exec = (runtime.exec ??= await import('../exec'))
+  if (n.latency)
+    await new Promise((ok) => {
+      setTimeout(ok, n.latency)
+    })
+  if (!n.online())
+    throw Object.assign(new Error(`offline: ${id} wasn't sent`), { name: 'OfflineError' })
+  const fails = n.fails.get(id)
+  if (fails?.length) throw fails.shift()
+  const fn = fns.get(id)
+  if (!fn) throw new FnError({ code: 'Q009', message: `Q009: no server function \`${id}\`` }, 404)
+  const scope = fakeScope(
+    exec,
+    n,
+    new Request(`http://localhost/_weft/fn/${id}`, {
+      method: kind === 'query' ? 'GET' : 'POST',
+      headers: runtime.conn ? { 'x-weft-conn': runtime.conn } : {},
+    }),
+  )
+  try {
+    return JSON.parse(JSON.stringify(await n.als.run(scope, () => call(exec, scope, fn))))
+  } catch (e) {
+    if (isRedirect(e)) return { r: e.href }
+    throw e instanceof StartError
+      ? new FnError(
+          { code: e.code, message: e.message, issues: e.issues, data: e.data },
+          e.status ?? 500,
+        )
+      : e
+  }
+}