lecodes-sdk 2.1.1 → 2.2.0

package/package.json

@@ -35,7 +35,7 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@letary/chisel": "^0.13.0"
+    "@letary/chisel": "^0.14.0"
   },
   "devDependencies": {
     "@types/bun": "^1.3.14",
@@ -45,7 +45,7 @@
     "marcidb-embedded": "^0.14.1",
     "sharp": "^0.35.2"
   },
-  "version": "2.1.1",
+  "version": "2.2.0",
   "files": [
     "src",
     "dist",

package/prompts/core.md

@@ -229,6 +229,7 @@ new WebSocket(url, headers?: Record<string, string>)
 // ===== STORAGE / DEVICE / MISC =====
 
 localStorage.getItem(key): string | null / .setItem(key, value) / .removeItem(key)   // nothing else
+signal<Line[]>([]).stored("cart")      // a signal kept on the device under the key (JSON values): back on the next launch
 
 device.platform: "ios" | "android" | "web"    // getter, no ()
 device.language: string                       // "en", "ru", …

package/prompts/ui.md

@@ -125,17 +125,15 @@ UIScrollable(...children)
 // visible rows (plus a buffer) are mounted. Use it instead of UIScrollable + map() whenever the item count
 // is large, grows over time, or is unknown.
 UIVirtualizedList<T>({
+    data: () => T[],                       // the rows, read reactively: write the signal, the list follows (new array, keys matched)
     keyOf: (item: T) => string,            // STABLE unique id per item (never the array index)
     render: (item: T) => UINodeChild,      // builds one row; called lazily as rows enter the window
     estimatedHeight: number | ((item: T) => number),  // px guess per row (real height measured after mount)
     overscan?: number,                     // extra px mounted above/below the viewport (default: one viewport)
     inverted?: boolean,                    // true = chat mode: starts scrolled to the end, append at bottom auto-scrolls
 })
-// Data is driven IMPERATIVELY (no diffing) — call these, never re-create the list:
-//   .setData(items: T[])                    // replace everything (diffed by key)
-//   .append(...items) / .prepend(...items)  // variadic; append = newest chat msg; prepend = history, no scroll jump
-//   .update(...items)                       // re-render rows with the same keyOf(); unknown keys ignored
-//   .removeByKey(...keys)
+// Rows added at the end scroll a chat at its bottom; rows added before the first (history) move nothing; a row
+// whose item is a new object re-renders. Never re-create the list.
 //   .itemCount (getter) / .getItem(key)
 //   .scrollTo(offset, animated?) / .scrollToKey(key, animated?) / .scrollToEnd(animated?) / .onScroll(cb(pos))
 //   .onEndReached(thresholdPx: number, cb)   // threshold FIRST and required; fires near the BOTTOM — load next page

package/src/chisel.ts

@@ -48,6 +48,8 @@ export interface ChiselVocab {
   signals: {
     /** Calls that create a signal (the roots of chisel's signal-type inference). */
     factories: string[]
+    /** Methods of a signal that return it (`signal(0).stored("key")`): a call of one on a signal is a signal. */
+    chain: string[]
     /** The property a signal is read through. */
     value: string
   }
@@ -131,8 +133,8 @@ export const chiselVocab: ChiselVocab = {
       "append", "insert", "remove", "setContent", "keepAlive", "url",
       "detents", "dismissible", "transition", "setSourceRect",
       "push", "pop", "popToRoot", "replace", "select",
-      // UITabs / UIVirtualizedList / the native views (NativeView, CameraView, MapView, QRScanner)
-      "badge", "setData", "update", "prepend", "removeByKey",
+      // UITabs / the native views (NativeView, CameraView, MapView, QRScanner)
+      "badge", "setData",
       "on", "off", "onReady", "onError", "onTap", "onMove", "onScan",
       "flyTo", "jumpTo", "fitPoints", "setPadding", "setUserLocation",
     ],
@@ -142,6 +144,7 @@ export const chiselVocab: ChiselVocab = {
   },
   signals: {
     factories: [ "signal", "computed" ],
+    chain: [ "stored" ],
     value: "value",
   },
   fusion: {

package/src/core/signals.ts

@@ -17,6 +17,8 @@
 //   fallback for engines without it (then stale subscribers just live until the run ends —
 //   every run executes in a fresh JSRuntime anyway).
 
+import { localStorage } from "../runtime/storage"
+
 interface WeakRefLike<T extends object> { deref(): T | undefined }
 
 const WeakRefImpl: new <T extends object>(target: T) => WeakRefLike<T> =
@@ -150,6 +152,12 @@ export interface Signal<T> {
   value: T,
   /** Read without subscribing the current effect/computed. */
   peek(): T,
+  /**
+   * Kept on the device under `key`: what the last run left there replaces the initial value (when
+   * it is there and reads as JSON), and every write is saved. JSON values only — a date, a class
+   * instance or a function does not survive the round trip. `signal<Line[]>([]).stored("cart")`.
+   */
+  stored(key: string): Signal<T>,
 }
 
 export interface Computed<T> {
@@ -161,6 +169,7 @@ export interface Computed<T> {
 class SignalImpl<T> {
   private _dep = new Dep()
   private _v: T
+  private _key?: string
 
   constructor(value: T) {
     this._v = value
@@ -174,12 +183,31 @@ class SignalImpl<T> {
   set value(next: T) {
     if (Object.is(next, this._v)) return
     this._v = next
+    if (this._key !== undefined) this._save()
     this._dep._notify()
   }
 
   peek(): T {
     return this._v
   }
+
+  stored(key: string): Signal<T> {
+    this._key = key
+    let raw: string | null = null
+    try { raw = localStorage.getItem(key) } catch { /* a host without storage: the value lives for this run */ }
+    if (raw !== null) {
+      try { this.value = JSON.parse(raw) as T } catch { /* not what this app wrote: the initial value stands */ }
+    }
+    return this
+  }
+
+  // Saved as it is written, so what the device keeps never lags behind the screen (no effect, no flush).
+  private _save(): void {
+    try {
+      if (this._v === undefined) localStorage.removeItem(this._key!)
+      else localStorage.setItem(this._key!, JSON.stringify(this._v))
+    } catch { /* storage-less host, or a value JSON cannot carry: the screen is right, the device forgets */ }
+  }
 }
 
 class ComputedImpl<T> implements Computation {

package/src/inject.ts

@@ -43,6 +43,8 @@ export { Net, NetPlayer, Replicated, NetEntity, type NetMessage, type NetRole, t
 // App-backend transport: the compiler-generated stubs of `*.server.ts` modules call these; user code
 // only ever imports its server functions (docs/backend-plan.md §4).
 export { __rpc, __channel, __serverOnly, RpcError } from "./runtime/rpc"
+// What a screen asks of the server, as reactive state: a request a screen follows, an action with its own busy / error.
+export { resource, action, dataOf, failureOf, type Loaded, type Failure, type Resource, type Action } from "./runtime/resource"
 export type { ChannelSubscription } from "./server/channel"
 export type { StoredFile, StoredImage } from "./server/files/models"
 export { AudioPlayer, VideoPlayer } from "./runtime/media"

package/src/runtime/resource.ts

@@ -0,0 +1,96 @@
+// What a screen asks of the app's server, as reactive state: a `resource` is a request a screen
+// follows (loading, ready, failed — ONE value), an `action` is a call with its own busy / error —
+// no try around a call, no flags by hand. Both take the compiled server stubs of ./rpc.ts, so a
+// failure is an RpcError: its status is the server's ApiError's, 0 when the request never reached
+// a server (no network, no backend) — `offline`.
+
+import { effect, signal, type Computed } from "../core/signals"
+
+/** Why a call failed: the server's refusal in its words — or `offline`, the request never reached
+ *  it (then `message` is the transport's note, not something to show; say it in your own words). */
+export type Failure = { readonly message: string, readonly offline: boolean }
+
+/** What was asked of the server, at any moment: one value a screen draws in its three states. */
+export type Loaded<T> =
+  | { readonly state: "loading" }
+  | { readonly state: "ready", readonly data: T }
+  | ({ readonly state: "failed" } & Failure)
+
+/** The data once it is there; `otherwise` until then. */
+export const dataOf = <T>(loaded: Loaded<T>, otherwise: T): T => loaded.state === "ready" ? loaded.data : otherwise
+
+/** The failure, or null while there is none. */
+export const failureOf = <T>(loaded: Loaded<T>): Failure | null => loaded.state === "failed" ? loaded : null
+
+const failure = (error: unknown): Failure => ({
+  message: error instanceof Error ? error.message : String(error),
+  offline: (error as { status?: unknown } | null)?.status === 0,
+})
+
+export interface Resource<T> {
+  /** The request now — read in an effect, a computed or a binding, the screen follows it. */
+  readonly value: Loaded<T>
+  /** Read without subscribing. */
+  peek(): Loaded<T>
+  /** Ask again. What is shown stays until the answer. */
+  reload(): void
+}
+
+/**
+ * What `load` answers, as a `Loaded` signal: asked at once, again when a signal `load` read changes
+ * and on `reload()`. An answer that arrives after a newer request was made is dropped. While the
+ * data is asked for again, what is there stays. With `initial` — rows the bundle carries — the data
+ * is ready from the start and the server's answer replaces it; a failure then leaves it as it is,
+ * since what is shown is real.
+ */
+export function resource<T>(load: () => Promise<T>, options: { initial?: T } = {}): Resource<T> {
+  const loaded = signal<Loaded<T>>(options.initial !== undefined ? { state: "ready", data: options.initial } : { state: "loading" })
+  const asked = signal(0)
+  let latest = 0
+  effect(() => {
+    asked.value
+    const mine = ++latest
+    let request: Promise<T>
+    try { request = load() } catch (error) { request = Promise.reject(error) }
+    if (loaded.peek().state !== "ready") loaded.value = { state: "loading" }
+    request.then(
+      (data) => { if (mine === latest) loaded.value = { state: "ready", data } },
+      (error) => { if (mine === latest && !(options.initial !== undefined && loaded.peek().state === "ready")) loaded.value = { state: "failed", ...failure(error) } },
+    )
+  })
+  return {
+    get value() { return loaded.value },
+    peek: () => loaded.peek(),
+    reload: () => { asked.value = asked.peek() + 1 },
+  }
+}
+
+export type Action<A extends unknown[], R> = ((...args: A) => Promise<R | null>) & {
+  /** True while a call runs; a call made meanwhile is ignored (it resolves to null). */
+  readonly busy: Computed<boolean>
+  /** Why the last call failed; null when it did not. Cleared as a call starts. */
+  readonly error: Computed<Failure | null>
+}
+
+/**
+ * Something the person does that the server must carry out. Resolves to what the server answered,
+ * or null when the call failed (then `error` says why) or was ignored while busy.
+ */
+export function action<A extends unknown[], R>(run: (...args: A) => Promise<R>): Action<A, R> {
+  const busy = signal(false)
+  const error = signal<Failure | null>(null)
+  const call = async (...args: A): Promise<R | null> => {
+    if (busy.peek()) return null
+    busy.value = true
+    error.value = null
+    try {
+      return await run(...args)
+    } catch (thrown) {
+      error.value = failure(thrown)
+      return null
+    } finally {
+      busy.value = false
+    }
+  }
+  return Object.assign(call, { busy, error })
+}

package/src/server/db/marci/query.ts

@@ -258,6 +258,8 @@ export interface Query<T extends ModelTypes, Sel = T["scalars"]> extends Promise
   aggregate<A extends T["aggregate"]>(query: A): Op<AggregateResult<T["model"], A>> & Sub<T["name"], NoInfer<A>>
 
   insert(data: T["insert"]): Op<T["id"]>
+  /** The new row by `select`'s shape — its defaults, dates and files as stored: one call, nothing to read back. */
+  insert<S extends T["query"]>(data: T["insert"], options: { select: S }): Promise<Rows<T, S>>
   update(id: IdArg<T["id"]>, data: T["update"]): Op<void>
   /** Applies `data` to every row the chain's `where` matches (all rows without one); resolves to the number of rows. */
   updateMany(data: T["update"]): Op<number>
@@ -454,7 +456,13 @@ export function createQueryLayer(options: QueryLayerOptions): { op: (descriptor:
           return Object.assign(op({ model, action: "aggregate", query: q }), { __select: q });
         },
 
-        insert: (data: any) => op({ model, action: "insert", data: options.prepareInsert ? options.prepareInsert(model, data) : data }),
+        insert: (data: any, extra?: { select?: Record<string, any> }) => {
+          const inserted = op({ model, action: "insert", data: options.prepareInsert ? options.prepareInsert(model, data) : data });
+          if (!extra?.select) return inserted;
+          // the row as stored, read back by the id the engine answered — a plain promise: a read is not a $transaction member
+          return inserted.then((id: any) => run({ model, action: "findFirst", query: resolveShape(model, { ...extra.select, $where: id }) }))
+            .then((row: any) => { if (row === null) throw new Error(`marcidb: ${model}: the row just inserted is gone`); return row; });
+        },
         update: (id: any, data: any) => op({ model, action: "update", id: idObject(model, id), data }),
         // `updateMany(data)`; the deprecated `updateMany(query, data)` form is told apart by arity
         updateMany: (a: any, b?: any) => (b === undefined

package/src/server/db/types.ts

@@ -9,7 +9,7 @@
 
 import type { Field, FieldMeta } from "./fields"
 import type { IdentityPublicFields, SessionPublicFields } from "../auth/models"
-import type { FileField, StoredFile, UploadedFile as File } from "../files/models"
+import type { FileField, FileWrite, StoredFile } from "../files/models"
 import type {
   CompareNumValue, CompareRefListValue, CompareRefValue, CompareStrValue, CompareValue, CustomSearchValue,
   FullTextSearch, JsonCondition, JsonPathWhere, Op, PrimitiveListUpdate, Query as MarciQuery, RefListUpdate,
@@ -72,7 +72,7 @@ type FieldInsert<S, Fld, M extends FieldMeta = MetaOf<Fld>> =
   M["kind"] extends "one" ? Nullable<M, Id<S, ModelName<S, Fld>>>
   : M["kind"] extends "many" | "list" ? Id<S, ModelName<S, Fld>>[]
   : M["kind"] extends "struct" ? Nullable<M, StructInsert<S, StructFieldsOf<Fld>>>
-  : M["kind"] extends "file" ? Nullable<M, Arr<M, File>>      // a new row takes uploads
+  : M["kind"] extends "file" ? Nullable<M, Arr<M, FileWrite>>      // a new row takes uploads
   : Nullable<M, Arr<M, TsOf<Fld>>>
 
 type RequiredKeys<F extends Fields> = {
@@ -99,7 +99,7 @@ type FieldUpdate<S, Fld, M extends FieldMeta = MetaOf<Fld>> =
   : M["kind"] extends "list" ? RefListUpdateOrdered<Id<S, ModelName<S, Fld>>>
   : M["kind"] extends "struct" ? RefUpdateStruct<StructInsert<S, StructFieldsOf<Fld>>, UpdateOf<S, StructFieldsOf<Fld>>> | null
   // an upload replaces; the stored file the field holds, handed back, keeps it; null / a shorter list deletes
-  : M["kind"] extends "file" ? Nullable<M, Arr<M, File | StoredFile>>
+  : M["kind"] extends "file" ? Nullable<M, Arr<M, FileWrite | StoredFile>>
   : M["array"] extends true ? TsOf<Fld>[] | PrimitiveListUpdate<TsOf<Fld>>
   : Nullable<M, TsOf<Fld> | (IsNum<M> extends true ? UpdateNumValue : never)>
 

package/src/server/files/models.ts

@@ -43,6 +43,11 @@ export type StoredImage = StoredFile & { width: number, height: number }
  */
 export type UploadedFile = { readonly name: string, readonly size: number, readonly type: string }
 
+/** What a file field is written with. A project's own type check sees the endpoint's `File` as the
+ *  app's (global.d.ts: a name and a size — the type is read from the bytes on arrival), so the write
+ *  asks for no more; what arrives is an `UploadedFile`. */
+export type FileWrite = { readonly name: string, readonly size: number }
+
 /** One `t.file()` field of the schema; `image` = it is a `t.image()`, with its rule. */
 export type FileField = { model: string, key: string, array: boolean, owner: string, image?: ImageRule }
 

package/src/ui/UIVirtualizedList.ts

@@ -1,3 +1,4 @@
+import { createBinding } from "../core/signals"
 import { Element, type Color, type DrawableStyle, type ElementStyle, type UIElementBase, type UINodeChild } from "./UINode"
 import { TREE_FLAG_REFRESH, TREE_FLAG_SCROLL, TREE_FLAG_VLIST_END, TREE_FLAG_VLIST_START, pin, tree, unpin } from "./tree"
 
@@ -10,6 +11,11 @@ export type UIVirtualizedListStyle = DrawableStyle & ElementStyle & {
 }
 
 export interface VListConfig<T> {
+    /** The rows, read reactively: the list follows the signals this reads, the way a container's
+     *  function children do. Rows are told apart by `keyOf`; a row whose item is another object
+     *  re-renders. Appended rows and rows added at the start are told from a rewrite (a chat at
+     *  its bottom follows what is appended; older history above moves nothing). */
+    data: () => T[]
     /** Stable unique key of an item. */
     keyOf: (item: T) => string
     /** Subtree factory — called when the item enters the window; the subtree lives until it
@@ -27,22 +33,10 @@ export interface VListConfig<T> {
 }
 
 /** A windowed (virtualized) list: only the items near the viewport are mounted — for long feeds
- *  and chats. Items are keyed; feed it via `setData`/`append`/`prepend`. */
+ *  and chats. Fed by `data`, a function over signals. */
 export interface UIVirtualizedList<T = unknown> extends UIElementBase<UIVirtualizedListStyle> {
     readonly type: "vlist"
 
-    /** Replace the data wholesale — vanished keys are unmounted by the window sync. */
-    setData(items: T[]): this
-    /** Append items to the end (auto-scrolls when `inverted` and resting at the bottom). */
-    append(...items: T[]): this
-    /** Insert at the start WITHOUT a scroll jump (the runtime compensates the offset). */
-    prepend(...items: T[]): this
-    /** Update items with the same keys: mounted ones re-render; the cached height persists until
-     *  re-measured. */
-    update(...items: T[]): this
-    /** Remove items by key. */
-    removeByKey(...keys: string[]): this
-
     /** Number of data items (mounted or not). */
     readonly itemCount: number
     /** The data item under `key`, if any. */
@@ -72,6 +66,7 @@ export class VListElement<T> extends Element<"vlist"> implements UIVirtualizedLi
     private readonly strl: (() => void)[] = []                         // startReached
     private _refreshCallback?: () => void | Promise<void>
 
+    private keys: string[] = []
     private items = new Map<string, T>()
     private mounted = new Map<string, any>()
     private keyOf: (item: T) => string
@@ -95,77 +90,61 @@ export class VListElement<T> extends Element<"vlist"> implements UIVirtualizedLi
             : () => config.estimatedHeight as number
         this._overscan = config.overscan ?? -1
         this._inverted = config.inverted ?? false
+        // The data binding is the element's (it goes with it); its first run waits a microtask so the
+        // edge thresholds chained after the constructor (`.onEndReached(…)`) are in the runtime's list
+        // state, which is created on the first write.
+        Promise.resolve().then(() => { if (this._h.id !== 0) createBinding(this, "data", () => this._apply(config.data())) })
     }
 
     // The runtime's list state is created on the first data write — after the app had its chance to
-    // set the edge thresholds (onEndReached / onStartReached come before setData in practice).
+    // set the edge thresholds.
     private _ensure(): void {
         if (this._inited || this._h.id === 0) return
         this._inited = true
         tree().vlistInit(this._h.id, this._overscan, this._inverted, this._startThreshold, this._endThreshold)
     }
 
-    private register(items: T[]): [string[], number[]] {
+    /** The data as it is now against what the runtime holds: rows added at the end or at the start
+     *  are inserts (the runtime anchors the scroll: a chat follows an append, history above moves
+     *  nothing), rows gone are removals, anything else a rewrite of the keys (measured heights stay). */
+    private _apply(next: T[]): void {
+        const prevKeys = this.keys
+        const prevItems = this.items
         const keys: string[] = []
         const estimates: number[] = []
-        for (const item of items) {
+        const items = new Map<string, T>()
+        for (const item of next) {
             const k = this.keyOf(item)
-            this.items.set(k, item)
+            if (items.has(k)) continue                      // a repeated key: the first row stands
+            items.set(k, item)
             keys.push(k)
             estimates.push(this.estimate(item))
         }
-        return [keys, estimates]
-    }
-
-    setData(items: T[]): this {
-        const prevItems = new Map(this.items)
-        const prevMounted = [...this.mounted.keys()]
-        this.items.clear()
-        const [keys, estimates] = this.register(items)
-        this._ensure()
-        if (this._h.id !== 0) {
-            tree().vlistSetKeys(this._h.id, keys, estimates)
-            for (const k of prevMounted) {
-                if (this.mounted.has(k) && this.items.get(k) !== prevItems.get(k)) {
-                    tree().vlistInvalidate(this._h.id, k)
-                }
-            }
-        }
-        return this
-    }
-
-    append(...items: T[]): this {
-        const [keys, estimates] = this.register(items)
-        this._ensure()
-        if (this._h.id !== 0) tree().vlistInsertKeys(this._h.id, -1, keys, estimates)
-        return this
-    }
-
-    prepend(...items: T[]): this {
-        const [keys, estimates] = this.register(items)
+        this.keys = keys
+        this.items = items
         this._ensure()
-        if (this._h.id !== 0) tree().vlistInsertKeys(this._h.id, 0, keys, estimates)
-        return this
-    }
-
-    update(...items: T[]): this {
-        for (const item of items) {
-            const k = this.keyOf(item)
-            if (!this.items.has(k)) continue
-            this.items.set(k, item)
-            if (this._h.id !== 0 && this.mounted.has(k)) tree().vlistInvalidate(this._h.id, k)
+        const id = this._h.id
+        if (id === 0) return
+        const n = prevKeys.length, m = keys.length
+        const same = (from: number) => { for (let i = 0; i < n; i++) if (keys[from + i] !== prevKeys[i]) return false; return true }
+        if (n === 0 || m === 0) {
+            tree().vlistSetKeys(id, keys, estimates)
+        } else if (m >= n && same(0)) {
+            if (m > n) tree().vlistInsertKeys(id, -1, keys.slice(n), estimates.slice(n))   // the same keys: nothing to tell
+        } else if (m > n && same(m - n)) {
+            tree().vlistInsertKeys(id, 0, keys.slice(0, m - n), estimates.slice(0, m - n))
+        } else {
+            // removals only: the new keys are the old ones in order, some left out
+            const gone: string[] = []
+            let j = 0
+            for (const k of prevKeys) { if (j < m && keys[j] === k) j++; else gone.push(k) }
+            if (m < n && j === m) tree().vlistRemoveKeys(id, gone)
+            else tree().vlistSetKeys(id, keys, estimates)
         }
-        return this
-    }
-
-    removeByKey(...keys: string[]): this {
-        const gone: string[] = []
-        for (const k of keys) {
-            if (!this.items.delete(k)) continue
-            gone.push(k)
+        // a mounted row whose item is another object re-renders; the others pick theirs up when they re-enter
+        for (const k of this.mounted.keys()) {
+            if (items.has(k) && prevItems.has(k) && items.get(k) !== prevItems.get(k)) tree().vlistInvalidate(id, k)
         }
-        if (this._h.id !== 0 && gone.length > 0) tree().vlistRemoveKeys(this._h.id, gone)
-        return this
     }
 
     get itemCount(): number { return this.items.size }
@@ -233,8 +212,8 @@ export class VListElement<T> extends Element<"vlist"> implements UIVirtualizedLi
     }
 }
 
-/** Create a virtualized list from a config (`keyOf` + `render` + `estimatedHeight` required),
- *  then feed it via `setData`/`append`/`prepend`. Give it a size (`flexGrow: 1` as a screen body). */
+/** Create a virtualized list from a config (`data` + `keyOf` + `render` + `estimatedHeight`
+ *  required). Give it a size (`flexGrow: 1` as a screen body). */
 export function UIVirtualizedList<T>(config: VListConfig<T>): UIVirtualizedList<T> {
     return new VListElement<T>(config)
 }

package/src/version.ts

@@ -4,7 +4,7 @@
 // same manifest). Its MAJOR is the bundle ↔ runtime contract: a bundle's `// sdk:` header line
 // and a host's embedded version must agree on the major for the host to run the bundle; minor
 // and patch never gate anything (features are detected, never versioned).
-export const SDK_VERSION = "2.1.1"
+export const SDK_VERSION = "2.2.0"
 
 /** The major of a semver string, or null when it is not one. */
 export const sdkMajor = (version: string | null | undefined): number | null => {