lecodes-sdk 2.2.3 → 2.2.5

package/src/inject.ts

@@ -104,7 +104,7 @@ export {
   UITabs, type UITabDef,
   defineTabs, type TabDef, type TabsHandle,
   UIWidget, type UIWidgetStyle,
-  UIOverlay, type UIWidgetContent,
+  type WidgetSet, type UIWidgetContent, type UIWidgetChild,
   UIModal, type UIModalStyle,
   UIBottomSheet, type UIBottomSheetStyle,
   UIPopover, type UIPopoverStyle,

package/src/server/db/defineDb.ts

@@ -145,10 +145,10 @@ const emitField = (owner: string, key: string, d: FieldDef, extra: string[]): st
   if (d.array && d.kind !== "many" && d.kind !== "list") type += "[]"
   if (d.optional) type += "?"
   if (d.isId) attrs.unshift("@id")
-  if (d.unique) attrs.push("@unique")
+  if (d.unique === true) attrs.push("@unique")
+  else if (typeof d.unique === "string") attrs.push(`@unique(${d.unique})`)
   if (d.index) attrs.push("@index")
-  // an array's default is filled in on insert (`withDefaults`): the engine reads `@default([])` as [""]
-  if (d.hasDefault && !d.array) attrs.push(`@default(${literal(d.default, d)})`)
+  if (d.hasDefault) attrs.push(`@default(${literal(d.default, d)})`)
   if (d.onDelete) attrs.push(`@onDelete(${ON_DELETE[d.onDelete]})`)
   if (d.fulltext) attrs.push(`@fulltext(${d.fulltext})`)
   if (d.vector) attrs.push(`@vector(${d.vector.metric})`)
@@ -228,6 +228,7 @@ export const defineDb = <const S extends Schema>(declared: S & ValidateRefs<S>,
   buildMeta({ ...own, [AUTH_SESSION_MODEL]: model({}) })
 
   let authModel: string | null = null
+  let seedFn: ((db: unknown) => Promise<void>) | null = null
   let sealed: { models: Record<string, Model>, schema: string, collections: Record<string, unknown>, auth: AuthBinding | null, files: FileField[] } | null = null
 
   const transport = () => {
@@ -272,20 +273,6 @@ export const defineDb = <const S extends Schema>(declared: S & ValidateRefs<S>,
       }
     }
     const metas = buildMeta(models)
-    // the defaults the schema does not carry: an array's (a copy per row)
-    const arrayDefaults: Record<string, [string, unknown[]][]> = {}
-    for (const meta of Object.values(metas)) {
-      arrayDefaults[meta.name] = Object.entries(meta.fields)
-        .filter(([, d]) => d.array && d.hasDefault && Array.isArray(d.default))
-        .map(([key, d]) => [key, d.default as unknown[]])
-    }
-    const withDefaults = (name: string, data: any) => {
-      const missing = arrayDefaults[name].filter(([key]) => data?.[key] === undefined)
-      if (!missing.length) return data
-      const out = { ...data }
-      for (const [key, value] of missing) out[key] = [...value]
-      return out
-    }
     const isFile = (name: string, key: string) => fileList.some(f => f.model === name && f.key === key)
     const meta = modelsMeta(metas, isFile)
     if (fileList.length) {
@@ -302,10 +289,9 @@ export const defineDb = <const S extends Schema>(declared: S & ValidateRefs<S>,
       models: meta,
       run: exec,
       // a single uuid key is generated client-side so `insert` needs no id (the .marci says @format(uuid))
-      prepareInsert: (name, raw) => {
-        const data = withDefaults(name, raw)
-        return metas[name].uuidId && data?.id == null ? { ...data, id: crypto.randomUUID() } : data
-      },
+      prepareInsert: (name, data) => metas[name].uuidId && data?.id == null ? { ...data, id: crypto.randomUUID() } : data,
+      // an upsert that creates the row needs the id a uuid model leaves to the client; the key wins when it is the id
+      prepareUpsert: (name, onInsert) => metas[name].uuidId ? { id: crypto.randomUUID(), ...(onInsert ?? {}) } : onInsert,
     })
     const collections: Record<string, unknown> = {}
     for (const name of Object.keys(own)) collections[name] = collection(name)
@@ -335,8 +321,18 @@ export const defineDb = <const S extends Schema>(declared: S & ValidateRefs<S>,
       db.auth = createAuthApi(() => seal().auth!)
       return db
     },
+    // The first rows, written by the host on an empty database (runtime.ts runSeed). Kept as given: a
+    // seed may be declared before or after .withAuth, and whether the database is empty is the host's
+    // question at the time it opens.
+    seed: (fn: (db: unknown) => Promise<void>) => {
+      if (typeof fn !== "function") throw new Error("defineDb(...).seed(fn): fn is the async function that writes the first rows")
+      if (seedFn) throw new Error("defineDb(...).seed(): called twice on one db — one seed writes every table")
+      seedFn = fn
+      return db
+    },
   }
   Object.defineProperties(db, {
+    $seed: { get: () => seedFn },
     $schema: { get: () => seal().schema },
     $models: { get: () => seal().models },
     $given: { get: () => own },

package/src/server/db/fields.ts

@@ -34,7 +34,8 @@ export type FieldDef = {
   kind: FieldKind
   scalar?: ScalarKind
   optional: boolean
-  unique: boolean
+  /** `true` = `@unique`; a string = `@unique(<group>)`: the fields of a model sharing the group are unique together. */
+  unique: boolean | string
   index: boolean
   hasDefault: boolean
   default?: unknown
@@ -64,8 +65,10 @@ export interface Field<T, M extends FieldMeta = FieldMeta> {
   readonly def: FieldDef
   /** Nullable column (`String?`). */
   optional(): Field<T, SetMeta<M, "optional", true>>
-  /** `@unique` (on a relation: one-to-one). */
-  unique(): Field<T, M>
+  /** `@unique` (on a relation: one-to-one). With a group name, the fields of the model that share it are
+   *  unique TOGETHER — `user: t.one("User").unique("pair"), post: t.one("Post").unique("pair")` is one
+   *  like per user and post; a null part is not constrained. */
+  unique(group?: string): Field<T, M>
   /** `@index` — used by `$where`, `$order`, aggregations. */
   index(): Field<T, M>
   /** `@default(...)`; `"now"` on `t.date()` → `now()`. Makes the field optional on insert. */
@@ -87,7 +90,7 @@ const create = <T, M extends FieldMeta>(def: FieldDef): Field<T, M> => {
   return {
     def,
     optional: () => next({ optional: true }),
-    unique: () => next({ unique: true }),
+    unique: (group?: string) => next({ unique: group ?? true }),
     index: () => next({ index: true }),
     default: (value: unknown) => next({ hasDefault: true, default: value }),
     array: () => next({ array: true }),

package/src/server/db/httpTransport.ts

@@ -11,16 +11,31 @@
 
 import type { MarciOp, MarciTransport } from "./marci/query"
 
-/** A failed marcidb request: `status` is the HTTP status (0 = network failure), `message` its body. */
+/** A failed marcidb request: `status` is the HTTP status (0 = network failure), `kind` the server's class of the
+ *  failure — a constraint (`unique`, `foreign_key`, `restrict`, `duplicate_id`), `not_found`, `bad_request`,
+ *  `unauthorized`, `internal` —, `field` the `Model.field` a constraint is about, the message its text. */
 export class MarciHttpError extends Error {
   readonly status: number
-  constructor(status: number, message: string) {
+  readonly kind: string
+  readonly field: string | null
+  constructor(status: number, message: string, kind?: string, field: string | null = null) {
     super(message)
     this.name = "MarciHttpError"
     this.status = status
+    this.kind = kind ?? (status === 404 ? "not_found" : status === 401 ? "unauthorized" : status >= 500 || status === 0 ? "internal" : "bad_request")
+    this.field = field
   }
 }
 
+/** The error of a failed response: the server's JSON body (`error`, `kind`, `field`), or its text. */
+const failure = (status: number, text: string): MarciHttpError => {
+  try {
+    const body = JSON.parse(text)
+    if (body && typeof body.error === "string") return new MarciHttpError(status, body.error, body.kind, body.field ?? null)
+  } catch { /* plain text */ }
+  return new MarciHttpError(status, text || `HTTP ${status}`)
+}
+
 export type MarciHttpOptions = {
   token?: string | null
   fetch?: typeof fetch
@@ -62,7 +77,7 @@ export const marciRequest = async (
     throw new MarciHttpError(0, `marcidb unreachable: ${(e as Error)?.message ?? e}`)
   }
   const text = await res.text()
-  if (!res.ok) throw new MarciHttpError(res.status, text || `HTTP ${res.status}`)
+  if (!res.ok) throw failure(res.status, text)
   if (!text) return undefined
   try { return JSON.parse(text) } catch { return text }
 }
@@ -77,6 +92,7 @@ export const marciHttpTransport = (baseUrl: string, options: MarciHttpOptions =
         case "findFirst":  return call(`${op.model}/findFirst`, op.query ?? {})
         case "insert":     return call(`${op.model}/insert`, op.data)
         case "update":     return call(`${op.model}/update/${encodeMarciId(op.id)}`, op.data).then(() => null)
+        case "upsert":     return call(`${op.model}/upsert`, { key: op.key, data: op.data, ...(op.onInsert !== undefined ? { onInsert: op.onInsert } : {}) })
         // no id in the path — the filter and the payload travel together in the body
         case "updateMany": return call(`${op.model}/updateMany`, { ...(op.query ?? {}), data: op.data })
         case "delete":     return call(`${op.model}/delete/${encodeMarciId(op.id)}`).then(() => null)

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

@@ -177,7 +177,7 @@ export type Op<T> = PromiseLike<T> & { readonly [__op]: T }
 
 // A transport-neutral operation descriptor and the pluggable transport that runs it. The HTTP transport
 // is selected by passing a URL string; marcidb-embedded provides an in-process FFI transport.
-export type MarciOp = { model: string, action: string, query?: any, data?: any, id?: any, journal?: JournalArgs }
+export type MarciOp = { model: string, action: string, query?: any, data?: any, id?: any, key?: any, onInsert?: any, journal?: JournalArgs }
 /** The arguments of a journal action (`$journalOpen` / `$journalRead` / `$journalDrop`). `wait` is in seconds. */
 export type JournalArgs = { name: string, on?: readonly JournalOp[], after?: number, limit?: number, wait?: number }
 export type MarciTransport = {
@@ -235,9 +235,11 @@ export interface Query<T extends ModelTypes, Sel = T["scalars"]> extends Promise
   readonly [__sel]: Effective<T, Sel>
   /** Filter (marcidb `$where`). Repeated calls are ANDed. */
   where(where: T["where"]): Query<T, Sel>
-  /** Sort by one field: `order("age", "desc")` or `order({ age: "desc" })`. */
+  /** Sort: `order("age", "desc")` or `order({ age: "desc" })`. A second `order()` adds the next key — ties on
+   *  the first are broken by it (`order("createdAt", "desc").order("id")`); the keys may also come as an array
+   *  in one call. Several keys sort in memory. */
   order(field: keyof T["order"] & string, direction?: "asc" | "desc"): Query<T, Sel>
-  order(order: T["order"]): Query<T, Sel>
+  order(order: T["order"] | T["order"][]): Query<T, Sel>
   limit(n: number): Query<T, Sel>
   skip(n: number): Query<T, Sel>
   /** Keyset cursor: rows strictly after this id in the current order (`$cursor`). */
@@ -261,6 +263,13 @@ export interface Query<T extends ModelTypes, Sel = T["scalars"]> extends Promise
   /** 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>
+  /** Writes the row `key` names — the id, or the fields of ONE unique index (a `@unique` field, all the fields of
+   *  a `@unique(<name>)` group): an update of `data` when it exists, an insert of key + data when not. `data` is
+   *  in the insert form (plain values, `{ id }` for a relation; no `$` operators). `onInsert` adds fields used
+   *  only when the row is created. Resolves to the id, like `insert`. */
+  upsert<K extends Partial<T["insert"]> | T["id"]>(key: K, data: Omit<T["insert"], keyof K>, options?: { onInsert?: Partial<T["insert"]> }): Op<T["id"]>
+  /** The row written, by `select`'s shape — as stored, whichever path the upsert took. */
+  upsert<K extends Partial<T["insert"]> | T["id"], S extends T["query"]>(key: K, data: Omit<T["insert"], keyof K>, options: { onInsert?: Partial<T["insert"]>, select: S }): Promise<Rows<T, S>>
   /** 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>
   /** @deprecated pass the filter through the chain: `db.user.where(w).updateMany(data)` (removed in the next minor). */
@@ -322,6 +331,9 @@ export type QueryLayerOptions = {
   run(op: MarciOp): Promise<any>;
   /** Hook for `insert` payloads (the lecodes SDK generates uuid ids here). */
   prepareInsert?(model: string, data: any): any;
+  /** Hook for the `onInsert` part of an `upsert` — the fields used only when the row is created (the lecodes SDK
+   *  puts a uuid id here). Receives what the caller gave (or undefined), returns what is sent. */
+  prepareUpsert?(model: string, onInsert: any): any;
 };
 
 const AGGREGATE_KEYS = ["$count", "$sum", "$avg", "$min", "$max"];
@@ -432,6 +444,10 @@ export function createQueryLayer(options: QueryLayerOptions): { op: (descriptor:
         return w ? { $where: w } : {};
       };
       const findMany = (): MarciOp => ({ model, action: "findMany", query: build() });
+      // the row as stored, read back by the id the engine answered — a plain promise: a read is not a $transaction member
+      const readBack = (written: Op<any>, select: Record<string, any>) =>
+        written.then((id: any) => run({ model, action: "findFirst", query: resolveShape(model, { ...select, $where: id }) }))
+          .then((row: any) => { if (row === null) throw new Error(`marcidb: ${model}: the row just written is gone`); return row; });
       return {
         get __op() { return findMany(); },
         get __select() { return build(); },
@@ -440,7 +456,15 @@ export function createQueryLayer(options: QueryLayerOptions): { op: (descriptor:
         finally: (onFinally?: any) => run(findMany()).finally(onFinally),
 
         where: (where: any) => make({ ...st, where: and(st.where, where) }),
-        order: (field: any, direction?: "asc" | "desc") => make({ ...st, order: typeof field === "string" ? { [field]: direction ?? "asc" } : field }),
+        order: (field: any, direction?: "asc" | "desc") => {
+          // one key per entry; an object with several keys is read in its key order
+          const given: any[] = typeof field === "string" ? [{ [field]: direction ?? "asc" }]
+            : Array.isArray(field) ? field
+            : Object.entries(field).map(([k, v]) => ({ [k]: v }));
+          const prev: any[] = st.order === undefined ? [] : Array.isArray(st.order) ? st.order : [st.order];
+          const keys = [...prev, ...given];
+          return make({ ...st, order: keys.length === 1 ? keys[0] : keys });
+        },
         limit: (n: number) => make({ ...st, limit: n }),
         skip: (n: number) => make({ ...st, skip: n }),
         after: (id: any) => make({ ...st, cursor: idObject(model, id) }),
@@ -458,12 +482,14 @@ export function createQueryLayer(options: QueryLayerOptions): { op: (descriptor:
 
         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; });
+          return extra?.select ? readBack(inserted, extra.select) : inserted;
         },
         update: (id: any, data: any) => op({ model, action: "update", id: idObject(model, id), data }),
+        upsert: (key: any, data: any, o?: { onInsert?: any, select?: Record<string, any> }) => {
+          const onInsert = options.prepareUpsert ? options.prepareUpsert(model, o?.onInsert) : o?.onInsert;
+          const written = op({ model, action: "upsert", key, data, ...(onInsert !== undefined ? { onInsert } : {}) });
+          return o?.select ? readBack(written, o.select) : written;
+        },
         // `updateMany(data)`; the deprecated `updateMany(query, data)` form is told apart by arity
         updateMany: (a: any, b?: any) => (b === undefined
           ? op({ model, action: "updateMany", query: whereOnly(), data: a })

package/src/server/db/types.ts

@@ -68,11 +68,11 @@ export type ScalarSelect<S, N extends keyof S> = { [K in (ScalarKeys<FieldsOf<S[
 
 // ───────────────────────────── insert ─────────────────────────────
 
-type FieldInsert<S, Fld, M extends FieldMeta = MetaOf<Fld>> =
+type FieldInsert<S, Fld, FW, 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, FileWrite>>      // a new row takes uploads
+  : M["kind"] extends "struct" ? Nullable<M, StructInsert<S, StructFieldsOf<Fld>, FW>>
+  : M["kind"] extends "file" ? Nullable<M, Arr<M, FW>>      // a new row takes uploads (a seed: a resource of the project too)
   : Nullable<M, Arr<M, TsOf<Fld>>>
 
 type RequiredKeys<F extends Fields> = {
@@ -84,12 +84,13 @@ type RequiredKeys<F extends Fields> = {
     : K
 }[keyof F]
 type Simplify<T> = { [K in keyof T]: T[K] } & {}
-type InsertOf<S, F extends Fields> = Simplify<
-  { [K in RequiredKeys<F>]: FieldInsert<S, F[K]> } &
-  { [K in Exclude<keyof F, RequiredKeys<F>>]?: FieldInsert<S, F[K]> }
+type InsertOf<S, F extends Fields, FW = FileWrite> = Simplify<
+  { [K in RequiredKeys<F>]: FieldInsert<S, F[K], FW> } &
+  { [K in Exclude<keyof F, RequiredKeys<F>>]?: FieldInsert<S, F[K], FW> }
 >
-export type Insert<S, N extends keyof S> = InsertOf<S, FieldsOf<S[N]>>
-type StructInsert<S, F extends Fields> = InsertOf<S, F>
+/** `FW` is what a file field is written with: an upload of the call; in a seed, a resource of the project as well. */
+export type Insert<S, N extends keyof S, FW = FileWrite> = InsertOf<S, FieldsOf<S[N]>, FW>
+type StructInsert<S, F extends Fields, FW = FileWrite> = InsertOf<S, F, FW>
 
 // ───────────────────────────── update ─────────────────────────────
 
@@ -138,7 +139,8 @@ export type Where<S, N extends keyof S> = WhereValue<WhereFieldsOf<S, FieldsOf<S
 type StructWhereFields<S, F extends Fields> = WhereFieldsOf<S, F>
 
 type OrderKeys<S, N extends keyof S> = (ValueKeys<FieldsOf<S[N]>> | keyof Id<S, N>) & keyof Row<S, N>
-/** ONE field and its direction: the engine sorts by a single field, so a second key is a type error. */
+/** One field and its direction. Several keys are several of these, in an array (`$order: [{ createdAt: "desc" },
+ *  { id: "asc" }]`) or chained `.order()` calls — an object with two keys is refused, since JSON promises no key order. */
 export type Order<S, N extends keyof S> = {
   [K in OrderKeys<S, N>]: { [P in K]: "asc" | "desc" } & { [P in Exclude<OrderKeys<S, N>, K>]?: never }
 }[OrderKeys<S, N>]
@@ -146,7 +148,7 @@ export type Order<S, N extends keyof S> = {
 /** The query object — marcidb's wire form: a select shape plus the `$`-clauses. */
 export type QueryObject<S, N extends keyof S> = Select<S, N> & {
   $where?: Where<S, N>
-  $order?: Order<S, N>
+  $order?: Order<S, N> | Order<S, N>[]
   $limit?: number
   $skip?: number
   $cursor?: Id<S, N>
@@ -164,7 +166,7 @@ export type AggregateQuery<S, N extends keyof S> = {
 // ───────────────────────────── query / db ─────────────────────────────
 
 /** The per-model type bag marcidb's generic `Query<T>` is parametrised by (what its codegen emits as `UserTypes`). */
-export type Types<S, N extends keyof S> = {
+export type Types<S, N extends keyof S, FW = FileWrite> = {
   name: N & string
   model: Row<S, N>
   id: Id<S, N>
@@ -173,7 +175,7 @@ export type Types<S, N extends keyof S> = {
   query: QueryObject<S, N>
   where: Where<S, N>
   order: Order<S, N>
-  insert: Insert<S, N>
+  insert: Insert<S, N, FW>
   update: Update<S, N>
   aggregate: AggregateQuery<S, N>
   reindex: false
@@ -185,7 +187,7 @@ export type Types<S, N extends keyof S> = {
  * `updateMany(data)`/`deleteMany()` write through the chain's `where`; a query placed in another query's
  * select is a sub-query. `Sel` is the projection: id + scalars until `select(...)` sets a shape.
  */
-export type Query<S, N extends keyof S, Sel = ScalarSelect<S, N>> = MarciQuery<Types<S, N>, Sel>
+export type Query<S, N extends keyof S, Sel = ScalarSelect<S, N>, FW = FileWrite> = MarciQuery<Types<S, N, FW>, Sel>
 /** The rows a query with projection `Q` resolves to (no field keys = id + scalars; sub-queries resolved). */
 export type Result<S, N extends keyof S, Q> = Rows<Types<S, N>, Q>
 /** `db.<model>` — the root query of a model. */
@@ -212,8 +214,22 @@ type DbBase<S extends Schema> = {
   readonly $auth: AuthBinding | null
   /** @internal the schema's `t.file()` fields (../files/models.ts). */
   readonly $files: FileField[]
+  /** @internal the seed, when the definition has one (`.seed(fn)`); the host runs it on an empty database. */
+  readonly $seed: ((db: SeedDb<S>) => Promise<void>) | null
+  /**
+   * The first rows of this database: run by the host ONCE, on a database that is empty, wherever the
+   * database opens (a check, a dev backend, the first deploy). Part of the definition, like sign-in:
+   * written on `defineDb(...)` itself. Inside, a file field takes a resource of the project — the path
+   * of a picture the design shows (`photo: row.photo`) — and stores it the way an upload is stored.
+   */
+  seed(fn: (db: SeedDb<S>) => Promise<void>): Db<S>
 }
 
+/** The db a seed writes through: the same queries, a file field taking a resource of the project (its path) too. */
+export type SeedDb<S extends Schema> = {
+  [N in keyof S & string as Uncapitalize<N>]: Query<Full<S>, N, ScalarSelect<Full<S>, N>, FileWrite | string>
+} & Pick<DbBase<S>, "$transaction">
+
 export type Db<S extends Schema> = DbBase<S> & {
   /**
    * Sign-in for this database: `model` is the project's model of a user. Adds the platform's `Session`
@@ -223,7 +239,10 @@ export type Db<S extends Schema> = DbBase<S> & {
    */
   withAuth<N extends keyof S & string>(options: { model: N }): DbWithAuth<S, N>
 }
-export type DbWithAuth<S extends Schema, N extends keyof S & string> = DbBase<S> & { readonly auth: Auth<S, N> }
+export type DbWithAuth<S extends Schema, N extends keyof S & string> = Omit<DbBase<S>, "seed"> & {
+  readonly auth: Auth<S, N>
+  seed(fn: (db: SeedDb<S>) => Promise<void>): DbWithAuth<S, N>
+}
 
 /** @internal */
 export type AuthBinding = { model: string, user: any, session: any, identity: any }

package/src/server/errors.ts

@@ -1,6 +1,9 @@
 /**
  * `throw new ApiError(404, "Not found")` inside an endpoint → the client's promise rejects with the
- * same status + message. Any other throw is a 500 (message hidden, logged to the server console).
+ * same status + message. A write the database refused for a reason a person could have caused reaches
+ * the app the same way, in the database's words: a taken unique value, a pointer at no row, a delete
+ * other rows forbid are 409, a row that is gone 404. Any other throw is a 500 (message hidden, logged
+ * to the server console).
  */
 export class ApiError extends Error {
   readonly status: number

package/src/server/files/db.ts

@@ -108,19 +108,38 @@ export const createFileLayer = (
     return { data: rest, files }
   }
 
-  const attach = async (field: FileField, id: string, owner: unknown, position: number): Promise<MarciOp> => {
-    const facts = field.image ? await filesSeam()!.image(id, field.image) : {}
+  const attach = async (field: FileField, id: string, owner: unknown, position: number, value?: unknown): Promise<MarciOp> => {
+    let facts = {}
+    if (field.image) {
+      try { facts = await filesSeam()!.image(id, field.image) } catch (e) {
+        // a resource of the project (a seed): the field and the path name what to fix
+        if (typeof value === "string") throw new Error(`${field.model}.${field.key}: "${value}": ${e instanceof Error ? e.message : e}`)
+        throw e
+      }
+    }
     return { model: FILE_MODEL, action: "update", id: { id }, data: { ...facts, [field.owner]: { $connect: owner }, position } }
   }
 
+  /** An upload of the current request — or, while a seed runs, a resource of the project named by its path. */
+  const uploadOf = async (value: unknown): Promise<string | undefined> => {
+    const seam = filesSeam()
+    const id = seam?.uploaded(value)
+    if (id) return id
+    return typeof value === "string" && seam?.resource ? seam.resource(value) : undefined
+  }
+
   const insert = async (op: MarciOp, index: number): Promise<Plan> => {
     const { data, files } = split(op.model, op.data)
     const after: MarciOp[] = []
     for (const [field, values] of files) {
       for (let position = 0; position < values.length; position++) {
-        const id = filesSeam()?.uploaded(values[position])
-        if (!id) throw new Error(`${op.model}.${field.key}: a new row takes uploaded files only — a file that is already stored belongs to its row`)
-        after.push(await attach(field, id, { $ref: String(index) }, position))
+        const value = values[position]
+        const id = await uploadOf(value)
+        if (!id) {
+          if (typeof value === "string" && filesSeam()?.resource) throw new Error(`${op.model}.${field.key}: "${value}" is not a file of the project`)
+          throw new Error(`${op.model}.${field.key}: a new row takes uploaded files only — a file that is already stored belongs to its row`)
+        }
+        after.push(await attach(field, id, { $ref: String(index) }, position, value))
       }
     }
     return { op: { ...op, data }, after }
@@ -134,11 +153,11 @@ export const createFileLayer = (
       const then: MarciOp[] = []
       for (let position = 0; position < values.length; position++) {
         const value = values[position]
-        const upload = filesSeam()?.uploaded(value)
+        const upload = await uploadOf(value)
         const id = upload ?? storedFileId(value)
         if (!id) throw new Error(`${op.model}.${field.key}: a file is expected — an upload, or the stored file the field already holds`)
         keep.push(id)
-        if (upload) then.push(await attach(field, upload, op.id, position))
+        if (upload) then.push(await attach(field, upload, op.id, position, value))
         // one that stays: its place in the list — and only where it IS this row's file
         else if (field.array) then.push({ model: FILE_MODEL, action: "updateMany", query: { $where: { id, [field.owner]: op.id } }, data: { position } })
       }

package/src/server/files/host.ts

@@ -29,12 +29,12 @@
 
 import { createReadStream } from "node:fs"
 import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises"
-import { join } from "node:path"
+import { basename, join } from "node:path"
 import { Readable } from "node:stream"
 import { currentRequest, type RequestContext } from "../context"
 import type { MarciOp, MarciTransport } from "../db/marci/query"
 import type { Db } from "../db/types"
-import { FILE_MODEL, setFilesSeam, type FilesSeam, type ImageFacts, type ImageRule } from "./models"
+import { FILE_MODEL, setFilesSeam, type FilesSeam, type ImageFacts, type ImageRule, type UploadedFile } from "./models"
 
 /** What the receiving process knows of one uploaded file; its bytes are in `<dir>/tmp/<id>`. */
 export type Upload = { id: string, name: string, type: string, size: number, width?: number, height?: number }
@@ -344,10 +344,18 @@ export type FilesHost = {
   install(): void
   /** The arguments with every `{ "$file": i }` turned into the `File` the endpoint receives. */
   adopt(args: unknown[], rc: RequestContext): Promise<unknown[]>
+  /** While a seed runs (runtime.ts runSeed): a resource of the project a row names by its path is read
+   *  through `read` and stored as an upload of `rc` would be — the field's rule applies, what the seed
+   *  writes nowhere is dropped by `finish`. Returns what ends it. */
+  seeding(rc: RequestContext, read: ResourceReader): () => void
   /** After the call, whatever it ended with. */
   finish(rc: RequestContext): Promise<void>
 }
 
+/** A resource of the project by the path the bundle has for it (`/images/a.jpg`): its bytes, or null when
+ *  the project has no such file. The host knows where the project's files are — a folder, a url. */
+export type ResourceReader = (path: string) => Promise<Uint8Array | null>
+
 const isPlaceholder = (v: unknown): v is { $file: number } =>
   typeof v === "object" && v !== null && typeof (v as { $file?: unknown }).$file === "number" && Object.keys(v).length === 1
 
@@ -434,10 +442,44 @@ export const createFilesHost = (cfg: FilesHostConfig): FilesHost => {
     }
   })().catch((e) => { ready = null; throw e }))
 
+  /** Uploads that lie in `tmp` become rows of `File` and files in place — the rows first, so a file on
+   *  disk always has its row — and the `File` objects the call sees, each known to the seam. */
+  const admit = async (uploads: Upload[], rc: RequestContext): Promise<UploadedFile[]> => {
+    await transport().batch(uploads.map(u => ({
+      model: FILE_MODEL, action: "insert",
+      data: { id: u.id, name: u.name, type: u.type, size: u.size, ...(u.width ? { width: u.width, height: u.height } : {}) },
+    })))
+    inFlight.set(rc, [...(inFlight.get(rc) ?? []), ...uploads.map(u => u.id)])
+    for (const u of uploads) names.set(u.id, u.name)
+    for (const u of uploads) await rename(join(cfg.dir, "tmp", u.id), join(cfg.dir, u.id))
+    return uploads.map((u) => {
+      const file = Object.freeze({ name: u.name, size: u.size, type: u.type })
+      uploaded.set(file, u.id)
+      return file
+    })
+  }
+
   return {
     enabled,
     install: () => setFilesSeam(enabled ? seam : null),
 
+    seeding: (rc, read) => {
+      if (!enabled) return () => {}
+      // a file belongs to one row: a picture two rows name is stored for each of them
+      seam.resource = async (path) => {
+        const bytes = await read(path)
+        if (!bytes) return undefined
+        await start()
+        const id = crypto.randomUUID()
+        const type = sniffType(bytes) ?? "application/octet-stream"
+        await writeFile(join(cfg.dir, "tmp", id), bytes)
+        const size = imageSize(bytes, type)
+        const [file] = await admit([{ id, name: basename(path), type, size: bytes.length, ...(size ?? {}) }], rc)
+        return uploaded.get(file!)
+      }
+      return () => { delete seam.resource }
+    },
+
     adopt: async (args, rc) => {
       const uploads = (rc.uploads ?? []) as Upload[]
       if (!uploads.length && !hasPlaceholder(args)) return args
@@ -448,21 +490,7 @@ export const createFilesHost = (cfg: FilesHostConfig): FilesHost => {
           const used = (await exec({ action: "aggregate", query: { $sum: "size" } }))?.sum ?? 0
           if (used + uploads.reduce((n, u) => n + u.size, 0) > cfg.quota) throw new UploadError(413, "the project's file storage is full")
         }
-        // the rows first, then the bytes into place: a file on disk always has its row
-        if (uploads.length) {
-          await transport().batch(uploads.map(u => ({
-            model: FILE_MODEL, action: "insert",
-            data: { id: u.id, name: u.name, type: u.type, size: u.size, ...(u.width ? { width: u.width, height: u.height } : {}) },
-          })))
-          inFlight.set(rc, uploads.map(u => u.id))
-          for (const u of uploads) names.set(u.id, u.name)
-          for (const u of uploads) await rename(join(cfg.dir, "tmp", u.id), join(cfg.dir, u.id))
-        }
-        const files = uploads.map((u) => {
-          const file = Object.freeze({ name: u.name, size: u.size, type: u.type })
-          uploaded.set(file, u.id)
-          return file
-        })
+        const files = uploads.length ? await admit(uploads, rc) : []
         const place = (v: unknown): unknown => {
           if (isPlaceholder(v)) return files[v.$file] ?? (() => { throw new UploadError(400, `the call names file ${v.$file}, and carries ${files.length}`) })()
           if (Array.isArray(v)) return v.map(place)

package/src/server/files/models.ts

@@ -96,6 +96,10 @@ export type FilesSeam = {
   /** The id of the `File` row behind an upload of the current request; undefined for anything else —
    *  a value the app sent as JSON is never an upload, whatever it looks like. */
   uploaded(value: unknown): string | undefined
+  /** While a seed runs: the id of a `File` row made from a resource of the project named by its path
+   *  (what a path literal of the design is in the server bundle); undefined for a path that is no file
+   *  of the project. Absent outside a seed: a string the app sent is never a file. */
+  resource?(path: string): Promise<string | undefined>
   url(id: string, name: string): string
   /** Make the upload `id` fit for a `t.image()` field (its bytes are rewritten in place) and say what
    *  it is now. Throws an `ApiError` for what is no picture. */

package/src/server/host.ts

@@ -6,9 +6,9 @@
  */
 
 export {
-  loadServerModules, createInvoker, createFileWriter, createSubscribeGuard, setChannelPublisher, setRequestProvider,
+  loadServerModules, createInvoker, createFileWriter, createSubscribeGuard, setChannelPublisher, setRequestProvider, runSeed, SeedError,
 } from "./runtime"
-export type { LoadedServer, InvokeResult, InvokerOptions, ServerRegistration } from "./runtime"
+export type { LoadedServer, InvokeResult, InvokerOptions, ServerRegistration, SeedOutcome } from "./runtime"
 export type { RequestContext } from "./context"
 export { createChannelHub } from "./channelHub"
 export type { ChannelHub, ChannelHubOptions, HubConnection, HubFanout } from "./channelHub"
@@ -26,7 +26,7 @@ export type { AuthState, AuthOps } from "./auth/types"
 export type { AppConfig } from "./auth/appConfig"
 export type { IdentityProvider } from "./auth/models"
 export { createFilesHost, receiveUploads, dropUploads, fileResponse, isMultipart, UploadError } from "./files/host"
-export type { FilesHost, FilesHostConfig, Heic, Sharp, Upload, UploadLimits } from "./files/host"
+export type { FilesHost, FilesHostConfig, Heic, ResourceReader, Sharp, Upload, UploadLimits } from "./files/host"
 export type { StoredFile, StoredImage } from "./files/models"
 import { FILE_MODEL, filePublicFields } from "./files/models"
 import { AUTH_IDENTITY_MODEL, AUTH_SESSION_MODEL, identityPublicFields, sessionPublicFields } from "./auth/models"

package/src/server/inject.ts

@@ -12,3 +12,6 @@ export { ApiError } from "./errors"
 export { channel } from "./channel"
 export { request } from "./context"
 export type { StoredFile, StoredImage } from "./files/models"
+/** The value an SVG source is to the client (`assetIcon(…)` compiles to `SvgSource(…)`): a shared module of
+ *  the design that names an icon per row loads on the server too. The server draws nothing with it. */
+export const SvgSource = (svg: string): { svg: string, tintColor: string | null } => ({ svg, tintColor: null })