@weft-js/start 0.1.1 → 0.1.3

package/src/changes.ts

@@ -20,7 +20,10 @@ import type { DbHandle } from './db/core'
 export type { LiveMode } from './data'
 
 /** What changed: never what it changed to. No `id`: the whole table. */
-export interface Change { table: string; id?: string }
+export interface Change {
+  table: string
+  id?: string
+}
 
 /** What a source learned about this database, by trying it. `feed` sees every change; `poll` only estimates. */
 export interface Probe {
@@ -64,7 +67,10 @@ export interface Source {
 }
 
 /** A table as `Source.defs` reports it. */
-export interface TableDef { name: string; pk: string[] }
+export interface TableDef {
+  name: string
+  pk: string[]
+}
 
 /** `dbChanges`: how to listen, and how a change turns into tags. */
 export interface ChangeOptions {
@@ -79,12 +85,25 @@ export interface ChangeOptions {
 }
 
 const NAME = Symbol.for('drizzle:Name')
-const nameOf = (t: unknown): string => (typeof t === 'string' ? t : (t as Record<symbol, string> | null)?.[NAME] ?? (() => { throw new StartError('R017', `\`dbChanges\` got something that isn't a table: ${String(t)}`, 'pass Drizzle tables, or their names') })())
+const nameOf = (t: unknown): string =>
+  typeof t === 'string'
+    ? t
+    : ((t as Record<symbol, string> | null)?.[NAME] ??
+      (() => {
+        throw new StartError(
+          'R017',
+          `\`dbChanges\` got something that isn't a table: ${String(t)}`,
+          'pass Drizzle tables, or their names',
+        )
+      })())
 
 const CORE = { sqlite: 'sqlite-core', postgresql: 'pg-core', mysql: 'mysql-core' }
 
 /** A table's primary key columns, from its Drizzle definition. */
-interface Key { name: string; primary?: boolean }
+interface Key {
+  name: string
+  primary?: boolean
+}
 
 async function pkOf(table: unknown, dialect: DbHandle['dialect']): Promise<string[]> {
   const { getTableConfig } = await import(/* @vite-ignore */ `drizzle-orm/${CORE[dialect]}`)
@@ -94,9 +113,18 @@ async function pkOf(table: unknown, dialect: DbHandle['dialect']): Promise<strin
 }
 
 /** `realtime({ changes: dbChanges(db, [todos, notes]) })`: these tables' writes reach `.live`, whoever made them. */
-export function dbChanges(db: { $weft?: DbHandle }, tables: unknown[], options: ChangeOptions = {}): Source {
+export function dbChanges(
+  db: { $weft?: DbHandle },
+  tables: unknown[],
+  options: ChangeOptions = {},
+): Source {
   const handle = db?.$weft
-  if (!handle?.changes) throw new StartError('R017', '`dbChanges` needs a client from `@weft-js/start/db/sqlite`, `/postgres` or `/mysql`', 'for MongoDB use `mongoChanges` from `@weft-js/db/mongo`; for another client, write a `Source`')
+  if (!handle?.changes)
+    throw new StartError(
+      'R017',
+      '`dbChanges` needs a client from `@weft-js/start/db/sqlite`, `/postgres` or `/mysql`',
+      'for MongoDB use `mongoChanges` from `@weft-js/db/mongo`; for another client, write a `Source`',
+    )
   const names = tables.map(nameOf)
   let source: Promise<Omit<Source, 'name' | 'tables'>> | undefined
   const load = () => (source ??= handle.changes!(names, options))
@@ -106,15 +134,25 @@ export function dbChanges(db: { $weft?: DbHandle }, tables: unknown[], options:
     tables: names,
     external: options.listener === 'external',
     tagged: options.tagged,
-    defs: () => Promise.all(tables.map(async t => ({ name: nameOf(t), pk: typeof t === 'string' ? [] : await pkOf(t, handle.dialect) }))),
-    probe: () => load().then(s => s.probe()),
-    start: (sink, probe) => load().then(s => s.start(sink, probe)),
-    settle: tags => load().then(s => s.settle?.(tags)),
+    defs: () =>
+      Promise.all(
+        tables.map(async (t) => ({
+          name: nameOf(t),
+          pk: typeof t === 'string' ? [] : await pkOf(t, handle.dialect),
+        })),
+      ),
+    probe: () => load().then((s) => s.probe()),
+    start: (sink, probe) => load().then((s) => s.start(sink, probe)),
+    settle: (tags) => load().then((s) => s.settle?.(tags)),
   }
 }
 
 /** Set by a platform, read at run time: this process lives for one request. */
-export function functionHost(env: Record<string, string | undefined> = (globalThis as unknown as { process?: { env: Record<string, string | undefined> } }).process?.env ?? {}): string | undefined {
+export function functionHost(
+  env: Record<string, string | undefined> = (
+    globalThis as unknown as { process?: { env: Record<string, string | undefined> } }
+  ).process?.env ?? {},
+): string | undefined {
   if (env.VERCEL) return 'Vercel'
   if (env.NETLIFY || env.NETLIFY_LOCAL) return 'Netlify'
   if (env.AWS_LAMBDA_FUNCTION_NAME) return 'AWS Lambda'
@@ -125,7 +163,11 @@ export function functionHost(env: Record<string, string | undefined> = (globalTh
 }
 
 /** What a change sends to live queries, as tags to refetch. */
-export interface Poke { t: string[]; /** Tag prefixes: `todos:` for every row of a table-level change. */ p?: string[]; /** Tags a barrier covered: a subscription with one of them is poked already. */ k?: string[] }
+export interface Poke {
+  t: string[]
+  /** Tag prefixes: `todos:` for every row of a table-level change. */ p?: string[]
+  /** Tags a barrier covered: a subscription with one of them is poked already. */ k?: string[]
+}
 
 /** Where a feed's pokes go: this instance, and the rest through the bus. */
 export interface FeedOut {
@@ -145,23 +187,116 @@ export interface Feed {
   readonly running: boolean
 }
 
-const unref = <T,>(t: T) => ((t as { unref?(): void } | null | undefined)?.unref?.(), t)
+const unref = <T>(t: T) => ((t as { unref?(): void } | null | undefined)?.unref?.(), t)
+
+function feedHandle(
+  source: Source,
+  known: Set<string>,
+  sink: Sink,
+  cancel: () => void,
+  barrier: number,
+): Feed {
+  // stopped → starting → running → stopped. A start that resolves after stop() (its turn has passed) is stopped at
+  // once, so a listener can't outlive the feed.
+  let phase: 'stopped' | 'starting' | 'running' = 'stopped'
+  let turn = 0
+  let stopping: (() => unknown) | undefined
+  return {
+    get running() {
+      return phase !== 'stopped'
+    },
+    covers(tag) {
+      const at = tag.indexOf(':')
+      return known.has(at < 0 ? tag : tag.slice(0, at))
+    },
+    async start(probe) {
+      if (phase !== 'stopped') return
+      phase = 'starting'
+      const mine = ++turn
+      let stop: (() => unknown) | undefined
+      try {
+        stop = await source.start(sink, probe)
+      } catch (e) {
+        if (turn === mine) phase = 'stopped'
+        throw e
+      }
+      if (turn !== mine) return void (await stop?.())
+      stopping = stop
+      phase = 'running'
+    },
+    async stop() {
+      cancel()
+      turn++
+      phase = 'stopped'
+      const stop = stopping
+      stopping = undefined
+      await stop?.()
+    },
+    async settle(tags) {
+      const ours = tags.filter((t) => this.covers(t))
+      if (!ours.length || !source.settle) return
+      let late: ReturnType<typeof setTimeout> | undefined
+      await Promise.race([
+        source.settle(ours),
+        new Promise<void>((ok) => {
+          late = unref(setTimeout(ok, barrier))
+        }),
+      ]).catch(() => {})
+      clearTimeout(late)
+    },
+  }
+}
+
+function addChanges(
+  list: Change[],
+  o: {
+    known: Set<string>
+    source: Source
+    pending: Set<string>
+    covered: Set<string>
+    prefixes: Set<string>
+    out: FeedOut
+    arm: () => void
+  },
+) {
+  const { known, source, pending, covered, prefixes, out, arm } = o
+  const seen: string[] = []
+  for (const c of list) {
+    if (!known.has(c.table)) continue
+    for (const t of source.tagged?.(c) ??
+      (c.id === undefined ? [c.table] : [c.table, `${c.table}:${c.id}`])) {
+      pending.add(t)
+      covered.delete(t) // a change after the barrier: no poke covers it
+      seen.push(t)
+    }
+    if (c.id === undefined) prefixes.add(`${c.table}:`)
+  }
+  if (!seen.length) return
+  out.bump?.(seen)
+  arm()
+}
 
 /** Batches a source's changes into pokes, held and throttled so a burst of writes is one refetch. */
-export function createFeed(source: Source, out: FeedOut, { hold = source.hold ?? 25, throttle = 250, barrier = 1000 } = {}): Feed {
+export function createFeed(
+  source: Source,
+  out: FeedOut,
+  { hold = source.hold ?? 25, throttle = 250, barrier = 1000 } = {},
+): Feed {
   const known = new Set(source.tables)
-  let pending = new Set<string>(), prefixes = new Set<string>(), covered = new Set<string>()
+  let pending = new Set<string>(),
+    prefixes = new Set<string>(),
+    covered = new Set<string>()
   let timer: ReturnType<typeof setTimeout> | undefined
   let last = 0
   let first: number | undefined
-  let stopping: (() => unknown) | undefined
-  let running = false
   let isDown = false
 
   const flush = () => {
     timer = first = undefined
     last = Date.now()
-    const t = [...pending], p = [...prefixes], k = [...covered]
+    const t = [...pending],
+      p = [...prefixes],
+      k = [...covered]
     pending = new Set()
     prefixes = new Set()
     covered = new Set()
@@ -172,27 +307,13 @@ export function createFeed(source: Source, out: FeedOut, { hold = source.hold ??
     const now = Date.now()
     first ??= now
     clearTimeout(timer)
-    timer = unref(setTimeout(flush, Math.max(Math.min(hold, first + throttle - now), last + throttle - now)))
+    timer = unref(
+      setTimeout(flush, Math.max(Math.min(hold, first + throttle - now), last + throttle - now)),
+    )
   }
 
-  const tagsOf = (change: Change) => source.tagged?.(change) ?? (change.id === undefined ? [change.table] : [change.table, `${change.table}:${change.id}`])
-
   const sink: Sink = {
-    changes(list) {
-      const seen: string[] = []
-      for (const c of list) {
-        if (!known.has(c.table)) continue
-        for (const t of tagsOf(c)) {
-          pending.add(t)
-          covered.delete(t) // a change after the barrier: no poke covers it
-          seen.push(t)
-        }
-        if (c.id === undefined) prefixes.add(`${c.table}:`)
-      }
-      if (!seen.length) return
-      out.bump?.(seen)
-      arm()
-    },
+    changes: (list) => addChanges(list, { known, source, pending, covered, prefixes, out, arm }),
     settled(tags) {
       for (const t of tags) {
         if (pending.delete(t)) covered.add(t)
@@ -204,7 +325,7 @@ export function createFeed(source: Source, out: FeedOut, { hold = source.hold ??
       covered = new Set()
     },
     lost() {
-      sink.changes(source.tables.map(table => ({ table })))
+      sink.changes(source.tables.map((table) => ({ table })))
     },
     down(why) {
       if (isDown) return
@@ -218,36 +339,14 @@ export function createFeed(source: Source, out: FeedOut, { hold = source.hold ??
     },
   }
 
-  return {
-    get running() { return running },
-    covers(tag) {
-      const at = tag.indexOf(':')
-      return known.has(at < 0 ? tag : tag.slice(0, at))
-    },
-    async start(probe) {
-      if (running) return
-      running = true
-      try {
-        stopping = await source.start(sink, probe)
-      } catch (e) {
-        running = false
-        throw e
-      }
-    },
-    async stop() {
+  return feedHandle(
+    source,
+    known,
+    sink,
+    () => {
       clearTimeout(timer)
       timer = undefined
-      running = false
-      const stop = stopping
-      stopping = undefined
-      await stop?.()
     },
-    async settle(tags) {
-      const ours = tags.filter(t => this.covers(t))
-      if (!ours.length || !source.settle) return
-      let late: ReturnType<typeof setTimeout> | undefined
-      await Promise.race([source.settle(ours), new Promise<void>(ok => { late = unref(setTimeout(ok, barrier)) })]).catch(() => {})
-      clearTimeout(late)
-    },
-  }
+    barrier,
+  )
 }

package/src/channel/connections.ts

@@ -0,0 +1,216 @@
+import { Box } from '@weft-js/core/internal'
+import {
+  DEV,
+  collect as boxes,
+  derived,
+  effect,
+  getOwner,
+  onCleanup,
+  state,
+  untrack,
+  type Derived,
+  type State,
+} from '@weft-js/core'
+import { currentScope, FnError, skip, StartError, track, type Fn } from '../data'
+import type { ChannelStatus, ConnectOptions, Connection, SharedBox } from '../channel'
+import {
+  acquire,
+  hold,
+  listOf,
+  post,
+  rejoin,
+  type Handle,
+  type Join,
+  type ListSpec,
+} from './socket'
+
+const NONE: never[] = []
+type View = Join | undefined
+
+/** The part `connect` and `shared` have in common: the current join, as the argument moves. */
+function follow(
+  fn: Fn,
+  arg: unknown,
+  options: ConnectOptions | undefined,
+  handle: Handle,
+  joined?: (j: Join) => void,
+): State<View> {
+  const view = state<View>(undefined)
+  effect(
+    () => {
+      const params = typeof arg === 'function' ? (arg as () => unknown)() : arg
+      if (params === skip) return undefined
+      return untrack(() => {
+        const j = acquire(fn, params)
+        j.handles.add(handle)
+        joined?.(j)
+        const stop = hold(j, options?.keep)
+        onCleanup(() => {
+          j.handles.delete(handle)
+          stop()
+        })
+        return j
+      })
+    },
+    (now) => {
+      view.value = now
+    },
+  )
+  return view
+}
+
+function owned(fn: Fn) {
+  if (!getOwner())
+    throw new StartError(
+      'W051',
+      DEV
+        ? `\`${fn.$id}.connect()\` 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,
+    )
+}
+
+/** `@weft-js/start/share`'s way in: a join that nothing on the page declared, so a tab shares this socket and its lifecycle. */
+export const connectBuiltIn = ($id: string) =>
+  connect({ kind: 'channel', $id, def: {} }, undefined, { keep: 0 })
+
+export function connect(
+  fn: Fn,
+  arg: unknown,
+  options?: ConnectOptions,
+): Connection<Record<string, never>, Record<string, never>> {
+  owned(fn)
+  if (currentScope()) {
+    const closed = { value: 'connecting' as ChannelStatus }
+    return {
+      status: closed,
+      room: { value: undefined },
+      error: undefined,
+      resets: { value: 0 },
+      collect: () => ({ value: NONE }),
+      on: () => () => {},
+      onReset: () => () => {},
+      send: () =>
+        Promise.reject(new FnError({ message: 'a channel has no socket on the server' }, 500)),
+      retry() {},
+    }
+  }
+  const handle: Handle = { on: new Map(), resets: new Set() }
+  const wanted: ListSpec[] = []
+  const view = follow(fn, arg, options, handle, (j) => {
+    for (const w of wanted) listOf(j, w)
+  })
+  return {
+    status: derived(() => view.value?.status.value ?? 'closed'),
+    room: derived(() => view.value?.key),
+    get error() {
+      return view.value?.error.value
+    },
+    resets: derived(() => view.value?.resets.value ?? 0),
+    collect(name, { max = 200, key } = {}) {
+      const spec: ListSpec = { name, max, key }
+      wanted.push(spec)
+      const had = untrack(() => view.value)
+      if (had) listOf(had, spec)
+      return derived(() => {
+        const j = view.value
+        return (j ? listOf(j, spec).box.value : NONE) as never[]
+      })
+    },
+    on(name, listener) {
+      const set = handle.on.get(name) ?? new Set()
+      handle.on.set(name, set)
+      set.add(listener)
+      const stop = () => void set.delete(listener)
+      onCleanup(stop)
+      return stop
+    },
+    onReset(listener) {
+      handle.resets.add(listener)
+      const stop = () => void handle.resets.delete(listener)
+      onCleanup(stop)
+      return stop
+    },
+    send(name, message) {
+      const j = untrack(() => view.value)
+      return j
+        ? post(j, name, message)
+        : Promise.reject(new FnError({ message: 'this channel is closed' }, 400))
+    },
+    retry() {
+      const j = untrack(() => view.value)
+      if (j?.refused) rejoin(j)
+    },
+  }
+}
+
+/** `Box.w` is the one way a write gets in, so a subclass sees every write, and `Instance` never touches it. */
+class Shared<T> extends Box<T> {
+  declare remote?: boolean
+  declare pending: number
+  declare base: { v: T; at: number }
+  declare view: State<View>
+  declare statusOf: Derived<ChannelStatus>
+  declare problem: State<unknown>
+  get status() {
+    return this.statusOf
+  }
+  get error() {
+    return this.problem.value
+  }
+  /** A server value: applied unless a local write is still on its way. */
+  apply(v: { v: T; at: number }) {
+    if (v.at >= this.base.at) this.base = v
+    if (!this.pending) this.quiet(this.base.v)
+  }
+  quiet(v: T) {
+    this.remote = true
+    this.w(v)
+    this.remote = false
+  }
+  override w(v: T) {
+    if (this.remote) return super.w(v)
+    const j = untrack(() => this.view.value)
+    if (!j) return super.w(v)
+    super.w(v)
+    this.pending++
+    this.problem.value = undefined
+    void track(
+      post(j, '$set', v)
+        .then(
+          () => {
+            this.pending--
+          },
+          (e) => {
+            this.pending--
+            this.problem.value = e
+          },
+        )
+        .finally(() => {
+          if (!this.pending) this.quiet(this.base.v)
+        }),
+    )
+  }
+}
+
+export function shared(fn: Fn, arg: unknown, options?: ConnectOptions): SharedBox<unknown> {
+  owned(fn)
+  const initial = fn.def.initial
+  const [b] = boxes(() => new Shared<unknown>(initial))
+  b.pending = 0
+  b.base = { v: initial, at: 0 }
+  b.problem = state<unknown>(undefined)
+  if (currentScope()) {
+    b.statusOf = { value: 'connecting' }
+    b.view = state<View>(undefined)
+    return b
+  }
+  const handle: Handle = { on: new Map(), resets: new Set(), value: (v) => b.apply(v) }
+  b.view = follow(fn, arg, options, handle, () => {
+    b.base = { v: initial, at: 0 }
+  })
+  b.statusOf = derived(() => b.view.value?.status.value ?? 'closed')
+  return b
+}