lecodes-sdk 2.0.11 → 2.0.12

package/package.json

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

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/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.11"
+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 => {