@coffer-org/sdk 3.3.0 → 3.4.0

package/dist/extend.js

@@ -1,10 +1,11 @@
-import { layoutToClient, fieldEntries, buildShape } from "./shelf.js";
+import { layoutToClient, fieldEntries, buildShape, checkFieldDeclaration } from "./shelf.js";
 import { z } from 'zod';
 export function defineExtend(e) {
     const keys = fieldEntries(e.fields).map(([k]) => k);
     const dup = keys.find((k, i) => keys.indexOf(k) !== i);
     if (dup)
         throw new Error(`[extend] ${e.id}: duplicate key '${dup}'`);
+    checkFieldDeclaration(e.fields, `[extend] ${e.id}`);
     return e;
 }
 export function extendMatches(e, library, shelf) {

package/dist/fields/normalize.d.ts

@@ -50,6 +50,7 @@ export interface FieldConfig {
 export type NormalizedOpts = {
     key?: string;
     value?: unknown;
+    store?: boolean;
     label?: string;
     options?: string | unknown[];
     slots?: string[];

package/dist/fields.d.ts

@@ -8,7 +8,7 @@ export type { Rules, View, FieldConfig } from './fields/normalize.ts';
 export { normalizeOpts } from './fields/normalize.ts';
 import { type Rules, type View } from './fields/normalize.ts';
 import { presets } from './field-presets.ts';
-export type CorePrim = 'text' | 'number' | 'date' | 'time' | 'datetime' | 'checkbox' | 'select' | 'json' | 'check' | 'measured' | 'relation' | 'file' | 'per-weekday' | 'lookup';
+export type CorePrim = 'text' | 'number' | 'date' | 'time' | 'datetime' | 'checkbox' | 'select' | 'json' | 'check' | 'measured' | 'relation' | 'file' | 'per-weekday';
 export type Prim = CorePrim | (string & {});
 export type ColumnType = 'text' | 'integer' | 'real' | 'boolean' | 'date' | 'time' | 'datetime';
 export type OptionIcon = {
@@ -48,6 +48,8 @@ export interface ComputeCtx {
         shelf: string;
     };
     self?: Record<string, unknown>;
+    parent?: Record<string, unknown>;
+    ref?: (key: string) => Promise<Record<string, unknown> | null>;
 }
 export type ComputeFn = (ctx: ComputeCtx) => unknown;
 export interface DividerEl {
@@ -184,6 +186,7 @@ export type FieldOptions = string | unknown[];
 export interface FieldCoreOpts {
     key?: string;
     value?: unknown;
+    store?: boolean;
     label?: string;
     rules?: Rules;
     view?: View;
@@ -204,6 +207,7 @@ export declare function wrapKey(opts: {
     emphasis?: 'hero' | 'muted';
     noLabel?: boolean;
     role?: 'cover' | 'avatar';
+    store?: boolean;
     derive?: import('./derive.ts').DeriveSpec;
 }, meta: FieldMeta): FieldItem | StaticEl | FieldMeta;
 export interface FieldMeta extends FieldClient {
@@ -522,21 +526,6 @@ export declare function perWeekday(o: {
 export type RowSubField = FieldClient & {
     key: string;
 };
-export interface LookupOpts extends FieldCoreOpts {
-    from: string;
-    pick: string[];
-}
-export declare function lookup(o: LookupOpts & {
-    key: string;
-}): FieldItem;
-export declare function lookup(o: LookupOpts & {
-    value: unknown;
-    key?: undefined;
-}): StaticEl;
-export declare function lookup(o: LookupOpts & {
-    key?: undefined;
-    value?: undefined;
-}): FieldMeta;
 export declare function clientToMeta(fc: FieldClient): FieldMeta;
 interface PeriodOpts extends FieldCoreOpts {
     parts?: PartsSpec;
@@ -723,7 +712,6 @@ declare const PRIMITIVES: {
     money: typeof money;
     code: typeof code;
     geo: typeof geo;
-    lookup: typeof lookup;
     perWeekday: typeof perWeekday;
     period: typeof period;
     file: typeof file;

package/dist/fields.js

@@ -134,8 +134,18 @@ export function wrapKey(opts, meta) {
             `"the server computes this field"; use value, the canonical spelling`);
     if (opts.derive)
         m = { ...m, derive: opts.derive, derived: true, hints: { ...m.hints, noEditControl: true } };
-    if (opts.key && 'value' in opts && opts.value !== undefined) {
+    const computed = opts.key && 'value' in opts && opts.value !== undefined;
+    if (opts.derive && opts.store === false)
+        throw new Error(`[wrapKey] '${opts.key}': derive writes a column on every write, so store: false contradicts it; ` +
+            `spell the computation as \`value\` instead.`);
+    if (opts.store === false && !computed)
+        throw new Error(`[wrapKey] '${opts.key ?? '(keyless)'}': store: false needs key + value — it drops the COLUMN of a ` +
+            `computed field, so that the server recomputes it on every read. A field without \`value\` has ` +
+            `nothing to recompute; a field without \`key\` already stores nothing.`);
+    if (computed) {
         m = { ...m, compute: opts.value, derived: true, hints: { ...m.hints, noEditControl: true } };
+        if (opts.store === false)
+            m = { ...m, virtual: true };
         return { key: opts.key, type: m };
     }
     if (opts.key)
@@ -625,7 +635,7 @@ export function measured(raw) {
     const rowSchema = z.object(partsRowShape({
         value: numSchema,
         unit: z.string().refine((v) => units.some((u) => u.value === v), { message: vmsg('measured_unit') }),
-    }, parts));
+    }, parts, required !== true));
     const s = z.unknown().transform((raw, ctx) => {
         const parsed = jsonValue(raw);
         if (typeof parsed === 'string') {
@@ -672,9 +682,7 @@ export function unit(raw) {
     const o = normalizeOpts(raw);
     const required = o.required ?? false;
     const units = resolveUnits(o.options);
-    const s = z
-        .string(reqErr())
-        .refine((v) => units.some((u) => u.value === v), { message: vmsg('measured_unit') });
+    const s = z.string(reqErr()).refine((v) => units.some((u) => u.value === v), { message: vmsg('measured_unit') });
     const meta = {
         kind: 'unit',
         label: o.label ?? '',
@@ -724,7 +732,7 @@ export function money(raw) {
     const rowSchema = z.object(partsRowShape({
         value: numSchema,
         currency: z.string().refine(isCurrencyCode, { message: vmsg('money_currency') }),
-    }, parts));
+    }, parts, required !== true));
     const s = z.unknown().transform((raw, ctx) => {
         const parsed = jsonValue(raw);
         if (typeof parsed === 'string') {
@@ -764,7 +772,7 @@ export function code(raw) {
     const required = o.required ?? false;
     const cfg = o.config ?? {};
     const parts = resolveParts(CODE_ROLES, o.parts);
-    const rowSchema = z.object(partsRowShape({ code: z.string(), lang: z.string() }, parts));
+    const rowSchema = z.object(partsRowShape({ code: z.string(), lang: z.string() }, parts, required !== true));
     const s = z.unknown().transform((raw, ctx) => {
         const parsed = jsonValue(raw);
         if (typeof parsed === 'string') {
@@ -804,15 +812,14 @@ export function geo(raw) {
         lat: z.number().min(-90).max(90),
         lng: z.number().min(-180).max(180),
         label: z.string().nullish(),
-    }, parts));
+    }, parts, required !== true));
     const clientCoordKeys = parts
         .filter((p) => (p.role === 'lat' || p.role === 'lng') && p.mode === 'stored')
         .map(partValueKey);
     const s = z.unknown().transform((raw, ctx) => {
         const parsed = jsonValue(raw);
         const p = parsed;
-        const noCoords = p == null ||
-            (typeof p === 'object' && clientCoordKeys.length > 0 && clientCoordKeys.every((k) => p[k] == null));
+        const noCoords = p == null || (typeof p === 'object' && clientCoordKeys.length > 0 && clientCoordKeys.every((k) => p[k] == null));
         if (noCoords) {
             if (required)
                 ctx.addIssue({ code: z.ZodIssueCode.custom, message: vmsg('required') });
@@ -854,20 +861,6 @@ export function perWeekday(o) {
         kind: 'per-weekday',
     };
 }
-export function lookup(raw) {
-    const o = normalizeOpts(raw);
-    const meta = {
-        kind: 'lookup',
-        label: o.label ?? '',
-        required: false,
-        prim: 'lookup',
-        column: 'text',
-        virtual: true,
-        hints: { from: o.from, pick: o.pick, compareWith: o.compareWith ?? null },
-        zod: z.any().optional(),
-    };
-    return wrapKey(o, meta);
-}
 export function clientToMeta(fc) {
     const { parts: _parts, ...rest } = fc;
     return { ...rest, column: 'text', zod: z.any() };
@@ -1066,7 +1059,7 @@ function makeRange(kind, isInt, raw) {
         n = n.max(cfg.max);
     const parts = resolveParts(RANGE_ROLES(isInt), o.parts);
     const rangeKeys = partValueKeys(parts);
-    const rowSchema = z.object(partsRowShape({ from: n, to: n }, parts));
+    const rowSchema = z.object(partsRowShape({ from: n, to: n }, parts, required !== true));
     const endpoint = endpointReader(parts, rangeKeys);
     const s = z.unknown().transform((raw, ctx) => {
         if (typeof raw === 'string') {
@@ -1165,7 +1158,6 @@ const PRIMITIVES = {
     money,
     code,
     geo,
-    lookup,
     perWeekday,
     period,
     file,

package/dist/parts.d.ts

@@ -24,5 +24,10 @@ export interface PartSlot {
 export declare function partValueKeys(parts: PartSlot[]): Record<string, string>;
 export declare function resolveParts(roles: RoleDef[], spec: PartsSpec | undefined): ResolvedPart[];
 export declare function partColumns(parts: ResolvedPart[]): Record<string, ColumnType>;
-export declare function partsRowShape(shape: Record<string, z.ZodTypeAny>, parts: ResolvedPart[]): Record<string, z.ZodTypeAny>;
+export declare function partsRowShape(shape: Record<string, z.ZodTypeAny>, parts: ResolvedPart[], tolerateNull?: boolean): Record<string, z.ZodTypeAny>;
+export declare function mixedOwnedStoredParts(parts: ResolvedPart[]): {
+    server: string[];
+    client: string[];
+} | null;
+export declare function mandatedClientParts(required: unknown, parts: ResolvedPart[]): string[];
 export declare function stripServerOwnedParts(value: Record<string, unknown>, parts: ResolvedPart[]): Record<string, unknown>;

package/dist/parts.js

@@ -72,7 +72,7 @@ export function partColumns(parts) {
             cols[p.key] = p.meta.column;
     return cols;
 }
-export function partsRowShape(shape, parts) {
+export function partsRowShape(shape, parts, tolerateNull = false) {
     const out = { ...shape };
     for (const p of parts)
         if (partValueKey(p) !== p.role)
@@ -82,11 +82,25 @@ export function partsRowShape(shape, parts) {
             out[p.role] = z.unknown().optional();
         else if (p.mode === 'computedStored')
             out[p.key] = z.unknown().optional();
-        else
-            out[p.key] = p.overridden ? p.meta.zod : (shape[p.role] ?? z.unknown().optional());
+        else {
+            const own = p.overridden ? p.meta.zod : (shape[p.role] ?? z.unknown().optional());
+            out[p.key] = tolerateNull && !(p.overridden && p.meta.required === true) ? own.nullable() : own;
+        }
     }
     return out;
 }
+export function mixedOwnedStoredParts(parts) {
+    const server = parts.filter((p) => p.mode === 'computedStored').map((p) => p.role);
+    const client = parts.filter((p) => p.mode === 'stored').map((p) => p.role);
+    return server.length > 0 && client.length > 0 ? { server, client } : null;
+}
+export function mandatedClientParts(required, parts) {
+    const speaks = (flag) => flag !== undefined && flag !== false;
+    const field = speaks(required);
+    return parts
+        .filter((p) => p.mode === 'stored' && (field || (p.overridden && speaks(p.meta.required))))
+        .map((p) => p.role);
+}
 function serverOwnedSlot(p) {
     if (!p.key)
         return p.role;

package/dist/shelf.d.ts

@@ -28,12 +28,14 @@ export interface ShelfDef {
 export declare function fieldEntries(items: LayoutEl[]): [string, FieldMeta][];
 export declare function storageColumns(key: string, field: FieldMeta): [string, ColumnType][];
 export declare function cellValue(field: FieldMeta, key: string, row: Record<string, unknown>): unknown;
+export declare function magnitudeSub(field: FieldMeta): string | undefined;
 export interface CollectionEntry {
     key: string;
     group: GroupEl;
 }
 export declare function collectionGroups(items: LayoutEl[]): CollectionEntry[];
 export declare function fieldMap(items: LayoutEl[]): Record<string, FieldMeta>;
+export declare function checkFieldDeclaration(fields: LayoutEl[], owner: string): void;
 export declare function defineShelf(m: ShelfDef): ShelfDef;
 export declare const SYSTEM_FIELDS: readonly ["id", "createdAt", "updatedAt"];
 export declare function titleKey(m: ShelfDef): string;

package/dist/shelf.js

@@ -4,6 +4,7 @@ import { resolveFlag } from "./condition.js";
 import { parseUrl } from "./fields/url.js";
 import { vmsg } from "./fields/validation.js";
 import { derivableKeys, legacyDeriveDeps } from "./derive.js";
+import { mixedOwnedStoredParts, mandatedClientParts } from "./parts.js";
 export function fieldEntries(items) {
     const out = [];
     for (const it of items) {
@@ -34,14 +35,21 @@ export function cellValue(field, key, row) {
     const out = {};
     let filled = false;
     for (const sub of Object.keys(field.columns)) {
-        const v = row[`${key}__${sub}`];
-        if (v == null || v === '')
+        const col = `${key}__${sub}`;
+        if (!(col in row))
             continue;
+        const v = row[col];
         out[sub] = v;
-        filled = true;
+        if (v != null && v !== '')
+            filled = true;
     }
     return filled ? out : undefined;
 }
+export function magnitudeSub(field) {
+    if (!field.columns)
+        return undefined;
+    return Object.keys(field.columns)[0];
+}
 export function collectionGroups(items) {
     const out = [];
     for (const it of items) {
@@ -65,14 +73,41 @@ export function fieldMap(items) {
     }
     return m;
 }
-function assertNoKeylessCompute(items, m) {
+function assertNoKeylessCompute(items, owner) {
     for (const it of items) {
         if (isStatic(it) && typeof it.value === 'function')
-            throw new Error(`${m.library}/${m.shelf}: computed element needs a key — the server computes it and needs a name to return it under`);
+            throw new Error(`${owner}: computed element needs a key — the server computes it and needs a name to return it under`);
         if (isGroup(it))
-            assertNoKeylessCompute(it.fields, m);
+            assertNoKeylessCompute(it.fields, owner);
     }
 }
+function warnMixedOwnedParts(items, owner, path = '') {
+    for (const it of items) {
+        if (isGroup(it)) {
+            warnMixedOwnedParts(it.fields, owner, it.key ? `${path}${it.key}.` : path);
+            continue;
+        }
+        if (!isField(it) || !it.type.parts)
+            continue;
+        const mixed = mixedOwnedStoredParts(it.type.parts);
+        if (!mixed)
+            continue;
+        const mandated = mandatedClientParts(it.type.required, it.type.parts);
+        if (!mandated.length)
+            continue;
+        console.warn(`${owner}: composite '${path}${it.key}' mandates a client-owned stored part (${mandated.join(', ')}) ` +
+            `and mixes it with a server-owned stored part (${mixed.server.join(', ')}) — ` +
+            `a mandated part is the client's to declare, so the write path does NOT materialize this composite ` +
+            `and the computed part stays absent until a client sends the field. Either drop \`required\` ` +
+            `(from the field or from the ${mandated.join('/')} filling), or give every stored part a \`value\` ` +
+            `(the composite becomes fully server-owned), or drop the \`key\` of ` +
+            `${mixed.client.join('/')} so it is unstored (pinned/computed and injected on read).`);
+    }
+}
+export function checkFieldDeclaration(fields, owner) {
+    assertNoKeylessCompute(fields, owner);
+    warnMixedOwnedParts(fields, owner);
+}
 export function defineShelf(m) {
     const keys = fieldEntries(m.fields).map(([k]) => k);
     const dup = keys.find((k, i) => keys.indexOf(k) !== i);
@@ -94,7 +129,7 @@ export function defineShelf(m) {
         console.warn(`[shelf] ${m.library}/${m.shelf}: ${titles.length} title fields (${titles.map(([k]) => k).join(', ')}) — '${titles[0][0]}' wins`);
     if (m.standalone !== false && !m.single && titleKey(m) === 'id')
         console.warn(`[shelf] ${m.library}/${m.shelf}: no title declared (field.title() or views.title) — the record renders no heading`);
-    assertNoKeylessCompute(m.fields, m);
+    checkFieldDeclaration(m.fields, `[shelf] ${m.library}/${m.shelf}`);
     const known = derivableKeys(m.fields);
     for (const [key, deps] of legacyDeriveDeps(m.fields)) {
         for (const dep of deps) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffer-org/sdk",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "type": "module",
   "engines": {
     "node": ">=24"