@quadrokit/client 0.1.0

package/README.md

@@ -0,0 +1,47 @@
+# `@quadrokit/client`
+
+Typed **4D REST** helper: small runtime (`fetch` with `credentials: 'include'`, paging, `$select` / `$expand`) plus a **code generator** that turns a catalog JSON into `.quadrokit/generated`.
+
+## Install
+
+```bash
+bun add @quadrokit/client
+```
+
+## CLI: `quadrokit-client`
+
+After install, the binary name is **`quadrokit-client`** (not the scoped package name):
+
+```bash
+bunx quadrokit-client generate \
+  --url 'http://localhost:7080/rest/$catalog' \
+  --token YOUR_TOKEN \
+  --out .quadrokit/generated
+```
+
+- **`--url`**: HTTP(S) catalog URL or `file:///absolute/path/to/catalog.json`
+- **`--token`**: optional `Authorization: Bearer …` for protected catalog endpoints
+- **`--out`**: output directory (default `.quadrokit/generated`)
+
+## Generated output
+
+- `types.gen.ts` — entity interfaces and `*Path` unions for `select`
+- `client.gen.ts` — `createClient({ baseURL })` with dataclasses, `authentify.login` when present in catalog, and `rpc()` escape hatch
+- `meta.json` — catalog `__NAME`, `sessionCookieName` hint
+
+## Runtime imports
+
+Apps and generated code import low-level pieces from:
+
+```ts
+import { QuadroHttp, type SelectedEntity } from '@quadrokit/client/runtime';
+```
+
+The main entry re-exports the runtime barrel.
+
+## Dev in this monorepo
+
+```bash
+bun run typecheck
+bun run src/cli.ts generate --url file://../../assets/catalog.json --out ../../.quadrokit/generated
+```

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@quadrokit/client",
+  "version": "0.1.0",
+  "description": "Typed 4D REST client and catalog code generator for QuadroKit",
+  "type": "module",
+  "bin": {
+    "quadrokit-client": "./src/cli.ts"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./runtime": {
+      "types": "./src/runtime/index.ts",
+      "import": "./src/runtime/index.ts"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "generate:fixture": "bun run src/cli.ts generate --url file://../../assets/catalog.json --out ../../.quadrokit/generated-demo"
+  },
+  "dependencies": {
+    "@quadrokit/shared": "workspace:*"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.4"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.11",
+    "@types/node": "^25.5.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,82 @@
+#!/usr/bin/env bun
+import { fileURLToPath } from 'node:url'
+import type { CatalogJson } from '@quadrokit/shared'
+import { writeGenerated } from './generate/codegen.js'
+
+function parseArgs(argv: string[]): {
+  command: string
+  url?: string
+  token?: string
+  out: string
+} {
+  let command = ''
+  let url: string | undefined
+  let token: string | undefined
+  let out = '.quadrokit/generated'
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--url' && argv[i + 1]) {
+      url = argv[++i]
+    } else if (a === '--token' && argv[i + 1]) {
+      token = argv[++i]
+    } else if (a === '--out' && argv[i + 1]) {
+      out = argv[++i]
+    } else if (!a.startsWith('-') && !command) {
+      command = a
+    }
+  }
+
+  return { command, url, token, out }
+}
+
+async function loadCatalog(url: string, token?: string): Promise<CatalogJson> {
+  if (url.startsWith('file:')) {
+    const path = fileURLToPath(url)
+    const file = Bun.file(path)
+    const text = await file.text()
+    return JSON.parse(text) as CatalogJson
+  }
+
+  const headers: Record<string, string> = {
+    Accept: 'application/json',
+  }
+  if (token) {
+    headers.Authorization = `Bearer ${token}`
+  }
+
+  const res = await fetch(url, { headers })
+  if (!res.ok) {
+    const t = await res.text()
+    throw new Error(`Failed to fetch catalog (${res.status}): ${t.slice(0, 500)}`)
+  }
+  return res.json() as Promise<CatalogJson>
+}
+
+async function main() {
+  const argv = process.argv.slice(2)
+  const { command, url, token, out } = parseArgs(argv)
+
+  if (command !== 'generate') {
+    console.error(`Usage: quadrokit-client generate --url <catalog_url> [--token <token>] [--out <dir>]
+
+Examples:
+  quadrokit-client generate --url http://localhost:7080/rest/\\$catalog --token secret
+  quadrokit-client generate --url file://./assets/catalog.json --out .quadrokit/generated
+`)
+    process.exit(1)
+  }
+  if (!url) {
+    console.error('Error: --url is required for generate.')
+    process.exit(1)
+  }
+
+  const catalog = await loadCatalog(url, token)
+  await writeGenerated(out, catalog)
+  console.error(`Wrote generated client to ${out}`)
+}
+
+main().catch((e) => {
+  console.error(e)
+  process.exit(1)
+})

package/src/generate/codegen.ts

@@ -0,0 +1,317 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import type { CatalogAttribute, CatalogDataClass, CatalogJson } from '@quadrokit/shared'
+import { sessionCookieName } from '@quadrokit/shared'
+
+function map4dType(attr: CatalogAttribute): string {
+  const t = attr.type ?? 'unknown'
+  switch (t) {
+    case 'long':
+    case 'word':
+      return 'number'
+    case 'string':
+      return 'string'
+    case 'bool':
+      return 'boolean'
+    case 'number':
+      return 'number'
+    case 'date':
+      return 'string'
+    case 'duration':
+      return 'string | number'
+    case 'image':
+      return 'string | null'
+    case 'object':
+      return 'Record<string, unknown>'
+    default: {
+      if (attr.kind === 'relatedEntity') {
+        return `${t} | null`
+      }
+      if (attr.kind === 'relatedEntities' || attr.kind === 'calculated') {
+        return 'unknown'
+      }
+      return 'unknown'
+    }
+  }
+}
+
+function selectionToEntity(selectionType: string): string {
+  if (selectionType.endsWith('Selection')) {
+    return selectionType.slice(0, -'Selection'.length)
+  }
+  return selectionType
+}
+
+function navigableRelations(dc: CatalogDataClass): { attr: string; targetClass: string }[] {
+  const out: { attr: string; targetClass: string }[] = []
+  for (const a of dc.attributes ?? []) {
+    if (a.kind === 'relatedEntities') {
+      out.push({
+        attr: a.name,
+        targetClass: selectionToEntity(a.type ?? 'unknown'),
+      })
+    }
+    if (a.kind === 'calculated' && a.behavior === 'relatedEntities' && a.type) {
+      out.push({ attr: a.name, targetClass: selectionToEntity(a.type) })
+    }
+  }
+  return out
+}
+
+function relationTargets(dc: CatalogDataClass): Record<string, string> {
+  const m: Record<string, string> = {}
+  for (const a of dc.attributes ?? []) {
+    if (a.kind === 'relatedEntity' && a.type) {
+      m[a.name] = a.type
+    }
+  }
+  return m
+}
+
+function keyNames(dc: CatalogDataClass): string[] {
+  const k = dc.key?.map((x) => x.name) ?? ['ID']
+  return k.length ? k : ['ID']
+}
+
+function collectPaths(
+  dc: CatalogDataClass,
+  byName: Map<string, CatalogDataClass>,
+  maxDepth: number
+): string[] {
+  const paths = new Set<string>()
+  const visit = (current: CatalogDataClass, prefix: string, depth: number) => {
+    for (const a of current.attributes ?? []) {
+      if (a.kind === 'storage' || a.kind === 'calculated' || a.kind === 'alias') {
+        const p = prefix ? `${prefix}.${a.name}` : a.name
+        paths.add(p)
+      }
+      if (a.kind === 'relatedEntity' && a.type && depth < maxDepth) {
+        const child = byName.get(a.type)
+        const base = prefix ? `${prefix}.${a.name}` : a.name
+        paths.add(base)
+        if (child) {
+          visit(child, base, depth + 1)
+        }
+      }
+    }
+  }
+  visit(dc, '', 0)
+  return [...paths].sort()
+}
+
+function emitInterface(dc: CatalogDataClass, _byName: Map<string, CatalogDataClass>): string {
+  const lines: string[] = []
+  lines.push(`export interface ${dc.name} {`)
+  for (const a of dc.attributes ?? []) {
+    if (a.kind === 'relatedEntities') {
+      continue
+    }
+    if (a.kind === 'calculated' && a.behavior === 'relatedEntities') {
+      continue
+    }
+    const opt = a.not_null || a.identifying ? '' : '?'
+    const ts = map4dType(a)
+    lines.push(`  ${a.name}${opt}: ${ts};`)
+  }
+  lines.push('}')
+  return lines.join('\n')
+}
+
+function emitTypes(catalog: CatalogJson): string {
+  const classes = catalog.dataClasses?.filter((d) => d.exposed) ?? []
+  const byName = new Map(classes.map((c) => [c.name, c]))
+  const interfaces = classes.map((c) => emitInterface(c, byName))
+  const pathTypes = classes.map((c) => {
+    const paths = collectPaths(c, byName, 2)
+    const name = `${c.name}Path`
+    const body = paths.length ? paths.map((p) => `'${p}'`).join('\n  | ') : 'never'
+    return `export type ${name} =\n  | ${body};`
+  })
+  return `/* eslint-disable */\n/* Auto-generated by @quadrokit/client — do not edit */\n\n${interfaces.join('\n\n')}\n\n${pathTypes.join('\n\n')}\n`
+}
+
+function emitClient(catalog: CatalogJson): string {
+  const classes = catalog.dataClasses?.filter((d) => d.exposed) ?? []
+  const dbName = catalog.__NAME ?? 'default'
+  const hasAuthentify = catalog.methods?.some(
+    (m) => m.name === 'authentify' && m.applyTo === 'dataStore'
+  )
+
+  const keyNamesRecord = Object.fromEntries(classes.map((x) => [x.name, keyNames(x)] as const))
+
+  const imports = `/* eslint-disable */\n/* Auto-generated by @quadrokit/client — do not edit */\n\nimport {\n  QuadroHttp,\n  makeDataClassApi,\n  attachRelatedApis,\n  callDatastorePath,\n  type CollectionHandle,\n  type CollectionOptions,\n  type SelectedEntity,\n} from '@quadrokit/client/runtime';\n`
+
+  const typeImports = classes.map((c) => c.name).join(', ')
+  const pathImports = classes.map((c) => `${c.name}Path`).join(', ')
+  const header = `${imports}\nimport type { ${typeImports}, ${pathImports} } from './types.gen.js';\n\n`
+
+  const metaExport = `
+export const quadrokitCatalogMeta = {
+  __NAME: ${JSON.stringify(dbName)},
+  sessionCookieName: ${JSON.stringify(sessionCookieName(catalog))},
+} as const;
+`
+
+  const configInterface = `
+export interface QuadroClientConfig {
+  baseURL: string;
+  fetchImpl?: typeof fetch;
+  defaultHeaders?: Record<string, string>;
+}
+`
+
+  const mapFunctions = classes
+    .map((c) => {
+      const nav = navigableRelations(c)
+      const relMap = JSON.stringify(relationTargets(c))
+      return `  function map${c.name}Row(http: QuadroHttp, raw: unknown): ${c.name} {
+    const row = raw as ${c.name};
+    const pk = (row as { ID?: number }).ID ?? (row as { id?: number }).id;
+    attachRelatedApis(
+      raw,
+      {
+        http,
+        parentClass: '${c.name}',
+        parentId: pk as number,
+        relationMap: ${relMap},
+        keyNames: ${JSON.stringify(keyNamesRecord)},
+      },
+      ${JSON.stringify(nav)},
+    );
+    return row;
+  }`
+    })
+    .join('\n\n')
+
+  const classBranches = classes
+    .map((c) => {
+      const relMap = JSON.stringify(relationTargets(c))
+      const kn = JSON.stringify(keyNames(c))
+      const pathsType = `${c.name}Path`
+      return `    ${c.name}: (() => {
+      const cfg = {
+        http,
+        className: '${c.name}',
+        relationMap: ${relMap},
+        keyNames: ${kn},
+      } as const;
+      const api = makeDataClassApi<${c.name}>(cfg);
+      return {
+        all<S extends readonly ${pathsType}[] = readonly []>(
+          options?: CollectionOptions & { select?: S },
+        ): CollectionHandle<S['length'] extends 0 ? ${c.name} : SelectedEntity<${c.name}, S>> {
+          const inner = api.all(options as CollectionOptions);
+          return {
+            ...inner,
+            delete: inner.delete.bind(inner),
+            release: inner.release.bind(inner),
+            get length() {
+              return inner.length;
+            },
+            [Symbol.asyncIterator]() {
+              const it = inner[Symbol.asyncIterator]();
+              return {
+                async next() {
+                  const n = await it.next();
+                  if (!n.done && n.value) {
+                    map${c.name}Row(http, n.value);
+                  }
+                  return n;
+                },
+              };
+            },
+          } as CollectionHandle<S['length'] extends 0 ? ${c.name} : SelectedEntity<${c.name}, S>>;
+        },
+        async get<S extends readonly ${pathsType}[] = readonly []>(
+          id: string | number,
+          options?: { select?: S },
+        ): Promise<(S['length'] extends 0 ? ${c.name} : SelectedEntity<${c.name}, S>) | null> {
+          const entity = await api.get(id, options);
+          if (entity) {
+            map${c.name}Row(http, entity);
+          }
+          return entity as (S['length'] extends 0 ? ${c.name} : SelectedEntity<${c.name}, S>) | null;
+        },
+        delete: (id: string | number) => api.delete(id),
+        query<S extends readonly ${pathsType}[] = readonly []>(
+          filter: string,
+          options?: CollectionOptions & { params?: unknown[]; select?: S },
+        ): CollectionHandle<S['length'] extends 0 ? ${c.name} : SelectedEntity<${c.name}, S>> {
+          const inner = api.query(filter, options as CollectionOptions);
+          return {
+            ...inner,
+            delete: inner.delete.bind(inner),
+            release: inner.release.bind(inner),
+            get length() {
+              return inner.length;
+            },
+            [Symbol.asyncIterator]() {
+              const it = inner[Symbol.asyncIterator]();
+              return {
+                async next() {
+                  const n = await it.next();
+                  if (!n.done && n.value) {
+                    map${c.name}Row(http, n.value);
+                  }
+                  return n;
+                },
+              };
+            },
+          } as CollectionHandle<S['length'] extends 0 ? ${c.name} : SelectedEntity<${c.name}, S>>;
+        },
+      };
+    })(),`
+    })
+    .join('\n')
+
+  const authentifyBlock = hasAuthentify
+    ? `
+    authentify: {
+      login: (body: { email: string; password: string }) =>
+        callDatastorePath(http, ['authentify', 'login'], { body }),
+    },`
+    : ''
+
+  const body = `
+export function createClient(config: QuadroClientConfig) {
+  const http = new QuadroHttp({
+    baseURL: config.baseURL,
+    fetchImpl: config.fetchImpl,
+    defaultHeaders: config.defaultHeaders,
+  });
+
+${mapFunctions}
+
+  return {${authentifyBlock}
+${classBranches}
+    rpc: (segments: string[], init?: { method?: 'GET' | 'POST'; body?: unknown }) =>
+      callDatastorePath(http, segments, init),
+    sessionCookieName: quadrokitCatalogMeta.sessionCookieName,
+    _http: http,
+  };
+}
+
+export type QuadroClient = ReturnType<typeof createClient>;
+`
+
+  return header + metaExport + configInterface + body
+}
+
+export async function writeGenerated(outDir: string, catalog: CatalogJson): Promise<void> {
+  await mkdir(outDir, { recursive: true })
+  await writeFile(path.join(outDir, 'types.gen.ts'), emitTypes(catalog), 'utf8')
+  await writeFile(path.join(outDir, 'client.gen.ts'), emitClient(catalog), 'utf8')
+  await writeFile(
+    path.join(outDir, 'meta.json'),
+    JSON.stringify(
+      {
+        __NAME: catalog.__NAME,
+        sessionCookieName: sessionCookieName(catalog),
+        generatedAt: new Date().toISOString(),
+      },
+      null,
+      2
+    ),
+    'utf8'
+  )
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Runtime and types for QuadroKit 4D REST clients.
+ * Generated `createClient` lives in `.quadrokit/generated/client.gen.ts` after `generate`.
+ */
+export * from './runtime/index.js'

package/src/runtime/collection.ts

@@ -0,0 +1,135 @@
+import type { QuadroHttp } from './http.js'
+import { buildListSearchParams, type ListQueryParams } from './query.js'
+import { unwrapEntityList } from './unwrap.js'
+
+export interface CollectionContext {
+  http: QuadroHttp
+  className: string
+  relationMap: Record<string, string>
+  /** Primary key attribute names (first wins for simple path). */
+  keyNames: readonly string[]
+  path: string
+  /** Optional entity-set URL from a previous response for `release()`. */
+  entitySetUrl?: string
+}
+
+export interface CollectionOptions extends ListQueryParams {
+  page?: number
+  pageSize?: number
+  select?: readonly string[]
+}
+
+export type MapRow<R> = (raw: unknown) => R
+
+function primaryKeyFromRow(row: unknown, keyNames: readonly string[]): string | number | undefined {
+  if (!row || typeof row !== 'object') {
+    return undefined
+  }
+  const o = row as Record<string, unknown>
+  for (const k of keyNames) {
+    if (k in o && o[k] != null) {
+      return o[k] as string | number
+    }
+  }
+  return undefined
+}
+
+/**
+ * Lazy paged collection: async iteration loads further pages; tracks PKs for `delete()`.
+ */
+export function createCollection<R>(
+  ctx: CollectionContext,
+  initialOptions: CollectionOptions,
+  mapRow: MapRow<R>
+): CollectionHandle<R> {
+  const seenIds = new Set<string | number>()
+  let entitySetUrl = ctx.entitySetUrl
+
+  async function fetchPage(page: number): Promise<unknown[]> {
+    const qs = buildListSearchParams(ctx.className, { ...initialOptions, page }, ctx.relationMap)
+    const res = await ctx.http.request(`${ctx.path}${qs}`)
+    const text = await res.text()
+    if (!res.ok) {
+      throw new Error(`List failed ${res.status}: ${text.slice(0, 200)}`)
+    }
+    const loc = res.headers.get('Content-Location') ?? res.headers.get('Location')
+    if (loc) {
+      entitySetUrl = loc.startsWith('http')
+        ? loc
+        : `${ctx.http.baseURL}${loc.startsWith('/') ? '' : '/'}${loc}`
+    }
+    const json = text ? JSON.parse(text) : []
+    return unwrapEntityList(ctx.className, json)
+  }
+
+  async function* iteratePages(): AsyncGenerator<R, void, undefined> {
+    let page = initialOptions.page ?? 1
+    const pageSize = initialOptions.pageSize ?? 50
+    while (true) {
+      const rows = await fetchPage(page)
+      if (!rows.length) {
+        break
+      }
+      for (const raw of rows) {
+        const mapped = mapRow(raw)
+        const pk = primaryKeyFromRow(raw, ctx.keyNames)
+        if (pk !== undefined) {
+          seenIds.add(pk)
+        }
+        yield mapped
+      }
+      if (rows.length < pageSize) {
+        break
+      }
+      page += 1
+    }
+  }
+
+  const iterable: AsyncIterable<R> = {
+    [Symbol.asyncIterator]() {
+      return iteratePages()[Symbol.asyncIterator]()
+    },
+  }
+
+  const handle: CollectionHandle<R> = {
+    ...iterable,
+    async delete(): Promise<void> {
+      const ids = [...seenIds]
+      if (!ids.length) {
+        return
+      }
+      await Promise.all(
+        ids.map((id) =>
+          ctx.http.void(`${ctx.className}(${encodeURIComponent(String(id))})`, {
+            method: 'DELETE',
+          })
+        )
+      )
+      seenIds.clear()
+    },
+    async release(): Promise<void> {
+      if (entitySetUrl) {
+        try {
+          await ctx.http.void(entitySetUrl.replace(ctx.http.baseURL, '') || entitySetUrl, {
+            method: 'DELETE',
+          })
+        } catch {
+          // Some servers ignore release; swallow
+        }
+        entitySetUrl = undefined
+      }
+    },
+    get length(): number {
+      return seenIds.size
+    },
+  }
+
+  return handle
+}
+
+export type CollectionHandle<R> = AsyncIterable<R> & {
+  delete(): Promise<void>
+  release(): Promise<void>
+  /** Number of entities seen while iterating (used after partial iteration). */
+  readonly length: number
+}

package/src/runtime/data-class.ts

@@ -0,0 +1,156 @@
+import { type CollectionHandle, type CollectionOptions, createCollection } from './collection.js'
+import type { QuadroHttp } from './http.js'
+import { buildEntityParams } from './query.js'
+import { unwrapEntity, unwrapEntityList } from './unwrap.js'
+
+export interface DataClassRuntimeConfig {
+  http: QuadroHttp
+  className: string
+  /** relation attribute name → target class name for $expand */
+  relationMap: Record<string, string>
+  keyNames: readonly string[]
+}
+
+export function makeDataClassApi<R = unknown>(cfg: DataClassRuntimeConfig) {
+  const path = `/${cfg.className}`
+
+  return {
+    all<S extends readonly string[] = readonly []>(
+      options?: CollectionOptions & { select?: S }
+    ): CollectionHandle<S extends readonly never[] ? R : R> {
+      return createCollection(
+        {
+          http: cfg.http,
+          className: cfg.className,
+          relationMap: cfg.relationMap,
+          keyNames: cfg.keyNames,
+          path,
+        },
+        options ?? {},
+        (raw) => raw as R
+      )
+    },
+
+    async get<S extends readonly string[] = readonly []>(
+      id: string | number,
+      options?: { select?: S }
+    ): Promise<R | null> {
+      const qs = options?.select?.length
+        ? buildEntityParams(cfg.className, options.select, cfg.relationMap)
+        : ''
+      const key = encodeURIComponent(String(id))
+      const body = await cfg.http.json<unknown>(`${cfg.className}(${key})${qs}`)
+      return unwrapEntity<R>(cfg.className, body) as R | null
+    },
+
+    async delete(id: string | number): Promise<boolean> {
+      const key = encodeURIComponent(String(id))
+      try {
+        await cfg.http.void(`${cfg.className}(${key})`, { method: 'DELETE' })
+        return true
+      } catch {
+        return false
+      }
+    },
+
+    query<S extends readonly string[] = readonly []>(
+      filter: string,
+      options?: CollectionOptions & { params?: unknown[]; select?: S }
+    ): CollectionHandle<S extends readonly never[] ? R : R> {
+      const paramFilter = substituteQueryParams(filter, options?.params)
+      return createCollection(
+        {
+          http: cfg.http,
+          className: cfg.className,
+          relationMap: cfg.relationMap,
+          keyNames: cfg.keyNames,
+          path,
+        },
+        { ...options, filter: paramFilter },
+        (raw) => raw as R
+      )
+    },
+  }
+}
+
+function substituteQueryParams(expr: string, params?: unknown[]): string {
+  if (!params?.length) {
+    return expr
+  }
+  let out = expr
+  params.forEach((p, i) => {
+    const placeholder = `:${i + 1}`
+    const lit = formatFilterLiteral(p)
+    out = out.split(placeholder).join(lit)
+  })
+  return out
+}
+
+function formatFilterLiteral(p: unknown): string {
+  if (p === null || p === undefined) {
+    return 'null'
+  }
+  if (typeof p === 'number') {
+    return String(p)
+  }
+  if (typeof p === 'boolean') {
+    return p ? 'true' : 'false'
+  }
+  const s = String(p).replace(/'/g, "''")
+  return `'${s}'`
+}
+
+export interface EntityNavigationConfig {
+  http: QuadroHttp
+  parentClass: string
+  parentId: string | number
+  relationMap: Record<string, string>
+  keyNames: Record<string, readonly string[]>
+}
+
+/** Nested collection under an entity, e.g. `Agency(1)/todayBookings`. */
+export function makeRelatedCollectionApi(
+  cfg: EntityNavigationConfig,
+  attributeName: string,
+  targetClassName: string
+) {
+  const basePath = `/${cfg.parentClass}(${encodeURIComponent(String(cfg.parentId))})/${attributeName}`
+
+  return {
+    list<S extends readonly string[] = readonly []>(
+      options?: CollectionOptions & { select?: S }
+    ): CollectionHandle<unknown> {
+      return createCollection(
+        {
+          http: cfg.http,
+          className: targetClassName,
+          relationMap: cfg.relationMap,
+          keyNames: cfg.keyNames[targetClassName] ?? ['ID'],
+          path: basePath,
+        },
+        options ?? {},
+        (raw) => raw
+      )
+    },
+  }
+}
+
+export function attachRelatedApis(
+  row: unknown,
+  cfg: EntityNavigationConfig,
+  relations: readonly { attr: string; targetClass: string }[]
+): void {
+  if (!row || typeof row !== 'object') {
+    return
+  }
+  const obj = row as Record<string, unknown>
+  for (const { attr, targetClass } of relations) {
+    Object.defineProperty(obj, attr, {
+      enumerable: false,
+      configurable: true,
+      value: makeRelatedCollectionApi(cfg, attr, targetClass),
+    })
+  }
+}
+
+export { unwrapEntityList }

package/src/runtime/datastore.ts

@@ -0,0 +1,25 @@
+import type { QuadroHttp } from './http.js'
+
+/** Call nested datastore paths like `authentify/login` (POST by default). */
+export async function callDatastorePath(
+  http: QuadroHttp,
+  segments: readonly string[],
+  init?: { method?: 'GET' | 'POST'; body?: unknown }
+): Promise<unknown> {
+  const path = `/${segments.join('/')}`
+  const method = init?.method ?? 'POST'
+  if (method === 'GET') {
+    return http.json(path, { method: 'GET' })
+  }
+  return http.json(path, {
+    method: 'POST',
+    body: init?.body !== undefined ? JSON.stringify(init.body) : undefined,
+  })
+}
+
+export function createDatastoreNamespace(
+  _http: QuadroHttp,
+  tree: Record<string, unknown>
+): Record<string, unknown> {
+  return tree
+}

package/src/runtime/errors.ts

@@ -0,0 +1,11 @@
+export class QuadroHttpError extends Error {
+  readonly status: number
+  readonly body: string
+
+  constructor(status: number, body: string) {
+    super(`Quadro HTTP ${status}: ${body.slice(0, 200)}`)
+    this.name = 'QuadroHttpError'
+    this.status = status
+    this.body = body
+  }
+}

package/src/runtime/http.ts

@@ -0,0 +1,64 @@
+import { QuadroHttpError } from './errors.js'
+
+export interface QuadroFetchOptions {
+  baseURL: string
+  fetchImpl?: typeof fetch
+  /** Extra headers on every request (e.g. Authorization for generate). */
+  defaultHeaders?: Record<string, string>
+}
+
+export function normalizeBaseURL(baseURL: string): string {
+  return baseURL.replace(/\/$/, '')
+}
+
+export class QuadroHttp {
+  constructor(private readonly opts: QuadroFetchOptions) {}
+
+  get baseURL(): string {
+    return normalizeBaseURL(this.opts.baseURL)
+  }
+
+  async request(path: string, init: RequestInit = {}): Promise<Response> {
+    const url = path.startsWith('http')
+      ? path
+      : `${this.baseURL}${path.startsWith('/') ? '' : '/'}${path}`
+    const headers = new Headers(init.headers)
+    if (!headers.has('Accept')) {
+      headers.set('Accept', 'application/json')
+    }
+    if (init.body !== undefined && !headers.has('Content-Type')) {
+      headers.set('Content-Type', 'application/json')
+    }
+    for (const [k, v] of Object.entries(this.opts.defaultHeaders ?? {})) {
+      if (!headers.has(k)) {
+        headers.set(k, v)
+      }
+    }
+    const fetchFn = this.opts.fetchImpl ?? fetch
+    return fetchFn(url, {
+      credentials: 'include',
+      ...init,
+      headers,
+    })
+  }
+
+  async json<T>(path: string, init: RequestInit = {}): Promise<T> {
+    const res = await this.request(path, init)
+    const text = await res.text()
+    if (!res.ok) {
+      throw new QuadroHttpError(res.status, text)
+    }
+    if (!text) {
+      return undefined as T
+    }
+    return JSON.parse(text) as T
+  }
+
+  async void(path: string, init: RequestInit = {}): Promise<void> {
+    const res = await this.request(path, init)
+    if (!res.ok) {
+      const text = await res.text()
+      throw new QuadroHttpError(res.status, text)
+    }
+  }
+}

package/src/runtime/index.ts

@@ -0,0 +1,23 @@
+export {
+  type CollectionContext,
+  type CollectionHandle,
+  type CollectionOptions,
+  createCollection,
+} from './collection.js'
+export {
+  attachRelatedApis,
+  type DataClassRuntimeConfig,
+  type EntityNavigationConfig,
+  makeDataClassApi,
+  makeRelatedCollectionApi,
+} from './data-class.js'
+export { callDatastorePath, createDatastoreNamespace } from './datastore.js'
+export { QuadroHttpError } from './errors.js'
+export {
+  normalizeBaseURL,
+  type QuadroFetchOptions,
+  QuadroHttp,
+} from './http.js'
+export type { Paths1, SelectedEntity } from './paths.js'
+export { buildListSearchParams, type ListQueryParams } from './query.js'
+export { unwrapEntity, unwrapEntityList } from './unwrap.js'

package/src/runtime/paths.ts

@@ -0,0 +1,42 @@
+/** Type-level helpers for `$select` dot paths (compile-time only). */
+
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (
+  k: infer I
+) => void
+  ? I
+  : never
+
+type PickOne<T, H extends string> = H extends keyof T & string
+  ? Pick<T, H>
+  : H extends `${infer K}.${infer R}`
+    ? K extends keyof T & string
+      ? NonNullable<T[K]> extends infer U
+        ? U extends object
+          ? { [P in K]: PickOne<U, R> }
+          : never
+        : never
+      : never
+    : never
+
+declare const selectBrand: unique symbol
+
+/** Entity narrowed to selected paths (branded for nominal distinction). */
+export type SelectedEntity<T, S extends readonly string[]> =
+  UnionToIntersection<
+    S[number] extends infer H ? (H extends string ? PickOne<T, H> : never) : never
+  > extends infer O
+    ? O extends object
+      ? O & { readonly [selectBrand]: S }
+      : never
+    : never
+
+/** Flat union of first-level and nested dot paths (codegen emits concrete unions). */
+export type Paths1<T> = T extends object
+  ? {
+      [K in keyof T & string]: NonNullable<T[K]> extends infer U
+        ? U extends object
+          ? K | `${K}.${Paths1<U>}`
+          : K
+        : K
+    }[keyof T & string]
+  : never

package/src/runtime/query.ts

@@ -0,0 +1,104 @@
+/** Build 4D REST query params ($skip, $top, $filter, $expand, $select). */
+
+export interface ListQueryParams {
+  page?: number
+  pageSize?: number
+  /** Dot-paths like `manager.name` → $expand + nested $select where possible. */
+  select?: readonly string[]
+  /** OData-style filter string (4D REST). */
+  filter?: string
+  orderby?: string
+}
+
+export function buildListSearchParams(
+  className: string,
+  opts: ListQueryParams,
+  _relationMap: Record<string, string>
+): string {
+  const params = new URLSearchParams()
+  const page = opts.page ?? 1
+  const pageSize = opts.pageSize ?? 50
+  const skip = (page - 1) * pageSize
+  if (skip > 0) {
+    params.set('$skip', String(skip))
+  }
+  params.set('$top', String(pageSize))
+  if (opts.filter) {
+    params.set('$filter', opts.filter)
+  }
+  if (opts.orderby) {
+    params.set('$orderby', opts.orderby)
+  }
+  const { expand, selectRoot } = buildExpandAndSelect(className, opts.select ?? [], _relationMap)
+  if (selectRoot.length) {
+    params.set('$select', selectRoot.join(','))
+  }
+  if (expand.length) {
+    params.set('$expand', expand.join(','))
+  }
+  const q = params.toString()
+  return q ? `?${q}` : ''
+}
+
+/** Query string for a single entity (only $select / $expand, no paging). */
+export function buildEntityParams(
+  className: string,
+  select: readonly string[] | undefined,
+  _relationMap: Record<string, string>
+): string {
+  if (!select?.length) {
+    return ''
+  }
+  const { expand, selectRoot } = buildExpandAndSelect(className, select, _relationMap)
+  const params = new URLSearchParams()
+  if (selectRoot.length) {
+    params.set('$select', selectRoot.join(','))
+  }
+  if (expand.length) {
+    params.set('$expand', expand.join(','))
+  }
+  const q = params.toString()
+  return q ? `?${q}` : ''
+}
+
+function buildExpandAndSelect(
+  _className: string,
+  paths: readonly string[],
+  _relationMap: Record<string, string>
+): { expand: string[]; selectRoot: string[] } {
+  if (!paths.length) {
+    return { expand: [], selectRoot: [] }
+  }
+  const rootSelect = new Set<string>()
+  const expandParts: string[] = []
+  const byRel = new Map<string, Set<string>>()
+
+  for (const p of paths) {
+    const dot = p.indexOf('.')
+    if (dot === -1) {
+      rootSelect.add(p)
+      continue
+    }
+    const rel = p.slice(0, dot)
+    const rest = p.slice(dot + 1)
+    if (!byRel.has(rel)) {
+      byRel.set(rel, new Set())
+    }
+    byRel.get(rel)!.add(rest)
+  }
+
+  for (const [rel, nested] of byRel) {
+    const nestedList = [...nested]
+    const inner = nestedList.length ? `($select=${nestedList.join(',')})` : ''
+    // Use navigation property name (4D / OData $expand), not the target class name.
+    expandParts.push(`${rel}${inner}`)
+    if (!rootSelect.has(rel)) {
+      rootSelect.add(rel)
+    }
+  }
+
+  return {
+    expand: expandParts,
+    selectRoot: [...rootSelect],
+  }
+}

package/src/runtime/unwrap.ts

@@ -0,0 +1,33 @@
+/** Normalize 4D REST JSON (array or `{ ClassName: [...] }`). */
+
+export function unwrapEntityList<T>(className: string, body: unknown): T[] {
+  if (Array.isArray(body)) {
+    return body as T[]
+  }
+  if (body && typeof body === 'object' && className in body) {
+    const v = (body as Record<string, unknown>)[className]
+    if (Array.isArray(v)) {
+      return v as T[]
+    }
+  }
+  if (body && typeof body === 'object' && '__ENTITIES' in body) {
+    const v = (body as { __ENTITIES?: unknown }).__ENTITIES
+    if (Array.isArray(v)) {
+      return v as T[]
+    }
+  }
+  return []
+}
+
+export function unwrapEntity<T>(className: string, body: unknown): T | null {
+  if (body == null) {
+    return null
+  }
+  if (Array.isArray(body)) {
+    return (body[0] as T) ?? null
+  }
+  if (typeof body === 'object' && className in body) {
+    return (body as Record<string, T>)[className] ?? null
+  }
+  return body as T
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "noEmit": true,
+    "types": ["bun", "node"]
+  },
+  "include": ["src/**/*.ts"]
+}