lecodes-sdk 2.0.10 → 2.0.12

package/package.json

@@ -45,7 +45,7 @@
     "marcidb-embedded": "^0.14.1",
     "sharp": "^0.35.2"
   },
-  "version": "2.0.10",
+  "version": "2.0.12",
   "files": [
     "src",
     "dist",

package/prompts/ui.md

@@ -41,6 +41,8 @@ const tabs = UITabs({
 Router.init(tabs)          // UITabs IS a UIScreen — present it directly
 // .select(id), .tab (getter), .onSelect(cb(id, i)) — fires on a bar tap, swipe, or select()
 // .badge(id, value) — true = dot, number/string = count pill, false/null/0 clears
+// Ambient, from any screen, no reference threading: UITabs.current (the visible tabs, or null) and
+//   UITabs.select("profile") — the twin of UIPager.current / UIPager.push
 // .pager — the UIPager underneath; UIPager.push(detail) from any screen keeps the bar
 // The bar is colored by the theme's roles (accent, textMuted, surface, border) — no keys of its
 //   own; one bar's own colors: tabs.bar.theme({ accent, surface }). Custom layout: UIPager below.

package/src/compile/index.ts

@@ -19,7 +19,7 @@ export {
   type ServerExportKind,
   type ServerManifest,
 } from "./serverSplit"
-export { deriveEndpointParams, EndpointTypeError, SyncEndpointError, UnawaitedUserQueryError, WrongSideGlobalError, type DeriveResult } from "./serverTypes"
+export { deriveEndpointParams, EndpointTypeError, ServerHelperImportError, UnawaitedUserQueryError, WrongSideGlobalError, type DeriveResult } from "./serverTypes"
 export {
   detectEntry,
   scanModulesFallback,

package/src/compile/serverSplit.ts

@@ -23,6 +23,12 @@ export const isServerPath = (path: string) => SERVER_FILE.test(path)
 /** Project path → endpoint-id prefix: no leading `./` or `/`, forward slashes. */
 export const serverModuleId = (path: string) => path.split("\\").join("/").replace(/^(\.\/|\/)+/, "")
 
+/**
+ * What an export of a server module is to the app: `fn` = an endpoint — an ASYNC function, called
+ * over the network; `channel` = a channel; `other` = server-only — a model, the db, a constant, or
+ * a helper: a function that is not async is used by server files alone, and the app's import of
+ * it is refused at compile time (serverTypes.ts), never a call that silently holds a promise.
+ */
 export type ServerExportKind = "fn" | "channel" | "other"
 export type ServerExport = { name: string, kind: ServerExportKind }
 
@@ -60,18 +66,9 @@ const IDENT = "[A-Za-z_$][\\w$]*"
 const classifyInit = (init: string): ServerExportKind => {
   const s = init.trimStart()
   if (/^channel\s*[<(]/.test(s)) return "channel"
-  if (/^(async\s+)?function\b/.test(s)) return "fn"
+  if (/^async\s+function\b/.test(s)) return "fn"
   if (/^async\b/.test(s)) return "fn"                              // async (…) => / async x =>
-  if (new RegExp(`^${IDENT}\\s*=>`).test(s)) return "fn"           // x => …
-  if (/^\(/.test(s)) {
-    // `(a, b) => …` — find the matching paren and look for `=>` (a type annotation may sit between)
-    let depth = 0
-    for (let i = 0; i < s.length; i++) {
-      if (s[i] === "(") depth++
-      else if (s[i] === ")") { depth--; if (depth === 0) return /^\s*(:[^=]*)?=>/.test(s.slice(i + 1)) ? "fn" : "other" }
-    }
-  }
-  return "other"
+  return "other"                                                    // a sync function, a value: the server's own
 }
 
 /** Exported names of a server module with their kinds. Default exports are rejected. */
@@ -87,8 +84,8 @@ export const scanServerExports = (source: string, path = "<server module>"): Ser
     if (i >= 0) found[i] = { at: found[i].at, name, kind }
     else found.push({ at, name, kind })
   }
-  // export [async] function name / export function* name
-  for (const m of src.matchAll(new RegExp(`(^|\\n)\\s*export\\s+(async\\s+)?function\\s*\\*?\\s*(${IDENT})`, "g"))) add(m.index!, m[3], "fn")
+  // export async function name = an endpoint; export function name = a helper of the server
+  for (const m of src.matchAll(new RegExp(`(^|\\n)\\s*export\\s+(async\\s+)?function\\s*\\*?\\s*(${IDENT})`, "g"))) add(m.index!, m[3], m[2] ? "fn" : "other")
   // export const|let|var name [: T] = init
   for (const m of src.matchAll(new RegExp(`(^|\\n)\\s*export\\s+(?:const|let|var)\\s+(${IDENT})\\s*(?::[^=]*?)?=\\s*([^\\n]*)`, "g"))) {
     add(m.index!, m[2], classifyInit(m[3]))
@@ -102,7 +99,7 @@ export const scanServerExports = (source: string, path = "<server module>"): Ser
       if (!local || /^type\s/.test(local)) continue
       const name = exported ?? local
       let kind: ServerExportKind = "other"
-      if (new RegExp(`(^|\\n)\\s*(async\\s+)?function\\s*\\*?\\s*${local}\\b`).test(src)) kind = "fn"
+      if (new RegExp(`(^|\\n)\\s*async\\s+function\\s*\\*?\\s*${local}\\b`).test(src)) kind = "fn"
       else {
         const decl = src.match(new RegExp(`(^|\\n)\\s*(?:const|let|var)\\s+${local}\\s*(?::[^=]*?)?=\\s*([^\\n]*)`))
         if (decl) kind = classifyInit(decl[2])

package/src/compile/serverTypes.ts

@@ -47,15 +47,16 @@ export class EndpointTypeError extends Error {
 }
 
 /**
- * In the app an endpoint's call is always a promise: it goes over the network. An endpoint that is
- * not `async` is imported with the type it was written with (`number`), so `const n = add(1, 2)`
- * type-checks and holds a promise. Declared `async`, the two agree.
+ * In the app an endpoint's call is always a promise: it goes over the network. A function of a
+ * server file that is not `async` is therefore not an endpoint but a helper, the server's own
+ * (serverSplit.ts): imported by the app it would keep the type it was written with (`number`), so
+ * `const n = add(1, 2)` would type-check and throw. The import is refused instead.
  */
-export class SyncEndpointError extends Error {
+export class ServerHelperImportError extends Error {
   readonly problems: string[]
   constructor(problems: string[]) {
-    super(`an endpoint is called over the network, so in the app its result is a promise — declare it async:\n  ${problems.join("\n  ")}`)
-    this.name = "SyncEndpointError"
+    super(`a function of a server file that is not async is a helper of the server, for server files only — the app calls endpoints, which are \`export async function\`:\n  ${problems.join("\n  ")}`)
+    this.name = "ServerHelperImportError"
     this.problems = problems
   }
 }
@@ -135,6 +136,38 @@ export type DeriveResult = {
   warnings: string[]
 }
 
+/**
+ * The app's imports of a server module's helpers: a named import, from a `*.server.ts` file, of an
+ * export the scan classed `other` that is a function. The checker resolves the import to its
+ * declaration, so the module is the one the import names, however it was spelled.
+ */
+const helperImports = (ts: TS, program: import("typescript").Program, checker: import("typescript").TypeChecker, modules: Record<string, ServerExport[]>, projectFiles: Set<string>): string[] => {
+  const kinds = new Map(Object.entries(modules).map(([path, exports]) => [normalizePath(path), new Map(exports.map(e => [e.name, e.kind]))]))
+  const out: string[] = []
+  for (const sf of program.getSourceFiles()) {
+    if (!projectFiles.has(sf.fileName) || sf.isDeclarationFile || isServerPath(sf.fileName)) continue
+    const file = serverModuleId(sf.fileName)
+    for (const statement of sf.statements) {
+      if (!ts.isImportDeclaration(statement) || !statement.importClause?.namedBindings || !ts.isNamedImports(statement.importClause.namedBindings)) continue
+      if (statement.importClause.isTypeOnly) continue
+      for (const spec of statement.importClause.namedBindings.elements) {
+        if (spec.isTypeOnly) continue
+        let symbol = checker.getSymbolAtLocation(spec.name)
+        if (symbol && symbol.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol)
+        const decl = symbol?.valueDeclaration ?? symbol?.declarations?.[0]
+        if (!symbol || !decl) continue
+        const target = normalizePath(decl.getSourceFile().fileName)
+        const name = (spec.propertyName ?? spec.name).text
+        if (kinds.get(target)?.get(name) !== "other") continue
+        if (checker.getTypeOfSymbolAtLocation(symbol, decl).getCallSignatures().length === 0) continue
+        const { line } = sf.getLineAndCharacterOfPosition(spec.getStart(sf))
+        out.push(`${file}:${line + 1}: ${name} of ${serverModuleId(target)}`)
+      }
+    }
+  }
+  return out
+}
+
 /**
  * Derive `{ "<module>#<fn>": ParamSchema[] }` for every function export of every `*.server.ts` entry.
  * Throws `EndpointTypeError` when a parameter type can't be validated at runtime.
@@ -196,11 +229,6 @@ export const deriveEndpointParams = async (entries: CompileEntry[], modules: Rec
   const params: Record<string, ParamSchema[]> = {}
   const warnings: string[] = []
   const problems: string[] = []
-  const sync: string[] = []
-  // a promise, or anything awaited the same way (a query handed back as it is); `any` is not judged
-  const awaitable = (type: import("typescript").Type): boolean =>
-    !!(type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown))
-    || (type.flags & ts.TypeFlags.Union ? (type as import("typescript").UnionType).types.every(awaitable) : !!type.getProperty("then"))
 
   for (const [path, exports] of Object.entries(modules)) {
     const sf = program.getSourceFile(normalizePath(path))
@@ -229,10 +257,6 @@ export const deriveEndpointParams = async (entries: CompileEntry[], modules: Rec
       }
       const sig = type.getCallSignatures()[0]
       if (!sig) { warnings.push(`${where}: not callable — unvalidated`); continue }
-      if (ex.kind === "fn" && !awaitable(checker.getReturnTypeOfSignature(sig))) {
-        const { line } = sf.getLineAndCharacterOfPosition(decl.getStart(sf))
-        sync.push(`${serverModuleId(path)}:${line + 1}: ${ex.name} — write \`async\` before it`)
-      }
       const list: ParamSchema[] = []
       for (const p of sig.getParameters()) {
         const pd = p.valueDeclaration as import("typescript").ParameterDeclaration | undefined
@@ -257,9 +281,10 @@ export const deriveEndpointParams = async (entries: CompileEntry[], modules: Rec
     }
   }
   if (problems.length) throw new EndpointTypeError(problems)
-  if (sync.length) throw new SyncEndpointError(sync)
   const wrongSide = wrongSideGlobals(ts, program, checker, new Set(files.keys()))
   if (wrongSide.length) throw new WrongSideGlobalError(wrongSide)
+  const helpers = helperImports(ts, program, checker, modules, new Set(files.keys()))
+  if (helpers.length) throw new ServerHelperImportError(helpers)
   const unawaited: string[] = []
   for (const path of Object.keys(modules)) {
     const sf = program.getSourceFile(normalizePath(path))

package/src/ui/UIPager.ts

@@ -31,6 +31,8 @@ export type UIPagerStyle = ElementStyle & DrawableStyle
 /** The pagers whose screen is currently visible, outermost → innermost. `UIPager.current` is the
  *  last (innermost). Maintained by each owned screen's onOpen/onClose via _activate/_deactivate. */
 const _activeStack: PagerElement[] = []
+/** @internal The active pagers, outermost → innermost — what `UITabs.current` searches. */
+export const _activePagers = (): readonly PagerElement[] => _activeStack
 
 /**
  * The screen-navigation element: sibling **tabs** that swipe natively side to side, each with its

package/src/ui/UITabs.ts

@@ -1,4 +1,4 @@
-import { PagerElement, type UIPager } from "./UIPager"
+import { PagerElement, _activePagers, type UIPager } from "./UIPager"
 import { ScreenElement, UIScreen } from "./UIScreen"
 import { UIButton } from "./UIButton"
 import { UIRow, UIColumn, type UIRow as UIRowType } from "./UIContainer"
@@ -63,6 +63,9 @@ export interface UITabs extends UIScreen {
   readonly bar: UIRowType,
 }
 
+/** The tabs by the pager each owns — what `UITabs.current` resolves through the active pagers. */
+const _byPager = new WeakMap<PagerElement, TabsElement>()
+
 export class TabsElement extends ScreenElement {
   private readonly ids: string[]
   private readonly _pagerEl: PagerElement
@@ -80,6 +83,7 @@ export class TabsElement extends ScreenElement {
     if (this.ids.length === 0) console.warn("UITabs: no tabs declared")
 
     this._pagerEl = new PagerElement({ flexGrow: 1 }, this.ids.map((id) => defs[id].screen))
+    _byPager.set(this._pagerEl, this)
 
     const buttons = this.ids.map((id, i) => {
       const def = defs[id]
@@ -173,10 +177,44 @@ export class TabsElement extends ScreenElement {
   }
 }
 
-/** Create the standard bottom-tab shell — see {@link UITabs}. Keys are tab ids in tab order;
- *  each tab needs a `label` and its root `screen` (plus an optional `icon`). */
-export function UITabs(tabs: Record<string, UITabDef>): UITabs {
-  return new TabsElement(tabs) as unknown as UITabs
+export interface UITabsConstructor {
+  /** Create the standard bottom-tab shell — see {@link UITabs}. Keys are tab ids in tab order;
+   *  each tab needs a `label` and its root `screen` (plus an optional `icon`). */
+  (tabs: Record<string, UITabDef>): UITabs
+  /** The tabs whose page is currently visible, or `null` when the visible screen is not a tab
+   *  of any — the twin of `UIPager.current`, so a screen switches tabs with no reference
+   *  threading: `UITabs.current?.select("services")`. With tabs nested inside a tab's page,
+   *  resolves to the innermost. */
+  readonly current: UITabs | null
+  /** `UITabs.current.select(id)` — switch the visible tabs to `id`; a console warning and no-op
+   *  when no tabs are on screen. */
+  select(id: string, animated?: boolean): void
+}
+
+const tabsFactory = (tabs: Record<string, UITabDef>): UITabs => new TabsElement(tabs) as unknown as UITabs
+
+/** Create the standard bottom-tab shell — see {@link UITabs}; `UITabs.current` / `UITabs.select(id)`
+ *  reach the visible tabs from anywhere. */
+export const UITabs = tabsFactory as unknown as UITabsConstructor
+
+const _resolveCurrent = (): TabsElement | null => {
+  const pagers = _activePagers()
+  for (let i = pagers.length - 1; i >= 0; i--) {
+    const tabs = _byPager.get(pagers[i])
+    if (tabs) return tabs
+  }
+  return null
+}
+
+// The ambient statics, attached the way UIPager's are (a statement that mutates a binding this
+// module declares is kept by chisel iff `UITabs` is reached — see UIPager.ts).
+Object.defineProperty(UITabs, "current", {
+  get: () => (_resolveCurrent() ?? null) as unknown as UITabs | null,
+})
+;(UITabs as any).select = (id: string, animated?: boolean) => {
+  const tabs = _resolveCurrent()
+  if (!tabs) { console.warn("UITabs.select: no tabs on the current screen"); return }
+  tabs.select(id, animated)
 }
 
 // ---- defineTabs — the design-stage twin ---------------------------------------------------------

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.0.10"
+export const SDK_VERSION = "2.0.12"
 
 /** The major of a semver string, or null when it is not one. */
 export const sdkMajor = (version: string | null | undefined): number | null => {