@stonecrop/schema 0.31.0 → 0.32.0

package/dist/src/doctype.js

@@ -1,343 +0,0 @@
-import { z } from 'zod';
-import { DoctypeFieldSchema, flattenFields, getDisplayField } from './field';
-import { toSlug } from './naming';
-/**
- * Cardinality for relationship links.
- * @public
- */
-export const Cardinality = z.enum(['atMostOne', 'one', 'noneOrMany', 'atLeastOne']).meta({
-    title: 'Cardinality',
-    description: 'Cardinality for relationship links between doctypes',
-});
-/**
- * Sync fetch strategy - data is fetched in the initial query.
- * @public
- */
-export const SyncFetch = z
-    .object({
-    /** Fetch method type */
-    method: z.literal('sync'),
-    /** Optional limit on number of records to fetch */
-    limit: z.number().int().positive().optional(),
-})
-    .meta({
-    title: 'SyncFetch',
-    description: 'Sync fetch strategy - data is fetched in the initial query',
-});
-/**
- * Lazy fetch strategy - data is fetched on demand in a separate query.
- * @public
- */
-export const LazyFetch = z
-    .object({
-    /** Fetch method type */
-    method: z.literal('lazy'),
-})
-    .meta({
-    title: 'LazyFetch',
-    description: 'Lazy fetch strategy - data is fetched on demand in a separate query',
-});
-/**
- * Custom fetch strategy - uses a custom handler function.
- * @public
- */
-export const CustomFetch = z
-    .object({
-    /** Fetch method type */
-    method: z.literal('custom'),
-    /** Serialized handler function to invoke */
-    handler: z.string(),
-})
-    .meta({
-    title: 'CustomFetch',
-    description: 'Custom fetch strategy - uses a custom handler function',
-});
-/**
- * Fetch strategy for link data loading.
- * - sync: fetched in the initial query
- * - lazy: fetched on demand in a separate query
- * - custom: uses a custom handler function
- * @public
- */
-export const FetchStrategy = z.discriminatedUnion('method', [SyncFetch, LazyFetch, CustomFetch]).meta({
-    title: 'FetchStrategy',
-    description: 'Fetch strategy for link data loading',
-});
-/**
- * Link declaration - describes a relationship from one doctype to another.
- * @public
- */
-export const LinkDeclaration = z
-    .object({
-    /** Target doctype slug */
-    target: z.string().min(1),
-    /** Cardinality of the relationship */
-    cardinality: Cardinality,
-    /** Backlink fieldname on the target doctype that points back to this link */
-    backlink: z.string().optional(),
-    /** Override default rendering component (AForm for 1:1, ATable for 1:many) */
-    component: z.string().optional(),
-    /** Fieldname of the corresponding Link field in the fields array */
-    fieldname: z.string().min(1).optional(),
-    /** Fetch strategy for loading nested data */
-    fetch: FetchStrategy.optional(),
-    /** Whether to block workflow actions until nested data is loaded (default: true) */
-    blockWorkflows: z.boolean().optional(),
-})
-    .meta({
-    title: 'LinkDeclaration',
-    description: 'Declares a relationship from one doctype to another',
-});
-/**
- * Action definition within a workflow
- * @public
- */
-export const ActionDefinition = z
-    .object({
-    /** Display label for the action */
-    label: z.string().min(1),
-    /** Fields that must have values before action can execute */
-    requiredFields: z.array(z.string()).optional(),
-    /** Workflow states where this action is available */
-    allowedStates: z.array(z.string()).optional(),
-    /** The state the record transitions to after this action executes */
-    nextState: z.string().optional(),
-    /** True for stateless command actions with no workflow effect at all (print, email, etc.) */
-    stateless: z.boolean().optional(),
-    /**
-     * True for an internal self-transition: the action runs within the current state without
-     * advancing the workflow (e.g. `save`, which mutates record data but stays put). Scoped by
-     * `allowedStates`, rendered as a self-loop in the graph, and has no `nextState`. Distinct from
-     * `stateless` (which has no workflow presence at all): a self-transition is graph-owned and,
-     * unlike a stateless command, persists record data on dispatch.
-     */
-    selfTransition: z.boolean().optional(),
-    /** JS function body stored as a string; executed client-side via AsyncFunction with injected API surface */
-    clientHandler: z.string().optional(),
-})
-    .meta({
-    title: 'ActionDefinition',
-    description: 'Action definition within a workflow',
-});
-/**
- * Reactive field-validation trigger — advisory, client-side only.
- *
- * A Trigger is a docbuilder-authored validator: when any field in `on` is edited, its
- * `clientHandler` runs (client-side, no rollback) and may flag a field inline to block save
- * in the UI. It is deliberately a **sibling** to {@link (ActionDefinition:type)}, not a member of it —
- * a reactive validator is not a user-invoked action, so it lives in the `triggers` map on
- * {@link (WorkflowMeta:type)} and never appears to action readers (transition/command dropdowns, the FSM graph).
- *
- * The two bindings are independent: `on` is the fire-set (which fields' edits run it), while the
- * `setError(field, msg)` call inside `clientHandler` chooses which field displays the error.
- * @public
- */
-export const TriggerDefinition = z
-    .object({
-    /** Optional display label; the map key is the trigger's identity */
-    label: z.string().optional(),
-    /** Fieldnames whose edits fire this trigger (fires when any listed field changes) */
-    on: z.array(z.string()),
-    /** JS function body stored as a string; run client-side with `{ record, value, setError }`. Advisory. */
-    clientHandler: z.string(),
-})
-    .meta({
-    title: 'TriggerDefinition',
-    description: 'Reactive field-validation trigger — advisory client-side',
-});
-/**
- * Whether a workflow action may run from `currentState`.
- *
- * Single source of truth for the "is this action available here" rule, shared by
- * the frontend (`getAvailableTransitions`) and the server-side dispatch guard so
- * the two can never disagree. Empty or absent `allowedStates` means the action is
- * available in ALL states — a plain `allowedStates.includes(currentState)` would
- * wrongly block such actions everywhere.
- *
- * @public
- */
-export function isActionAllowedInState(action, currentState) {
-    const allowedStates = action.allowedStates;
-    if (!allowedStates || allowedStates.length === 0)
-        return true;
-    return allowedStates.includes(currentState);
-}
-/**
- * DocBuilder graph layout — node positions for the workflow-state graph, keyed by state name.
- * Pure authoring view-state: persisted in the doctype JSON so an author's manual arrangement
- * survives reloads, but — exactly like {@link (WorkflowMeta:type)}'s `triggers` — it is client-only
- * and never mirrored into the runtime GraphQL SDL (see the WorkflowMeta type in the host SDLs, which
- * expose only `states`/`actions`). The shape mirrors VueFlow's node fields; `position` is the node's
- * canvas coordinate and `targetPosition`/`sourcePosition` are the handle sides.
- * @public
- */
-export const WorkflowLayout = z.record(z.string(), z.object({
-    position: z.object({ x: z.number(), y: z.number() }).optional(),
-    targetPosition: z.enum(['left', 'top', 'right', 'bottom']).optional(),
-    sourcePosition: z.enum(['left', 'top', 'right', 'bottom']).optional(),
-}));
-/**
- * Workflow metadata - states and actions for a doctype
- * @public
- */
-export const WorkflowMeta = z
-    .object({
-    /** List of workflow states */
-    states: z.array(z.string()).optional(),
-    /** Actions available in this workflow */
-    actions: z.record(z.string(), ActionDefinition).optional(),
-    /** Reactive field-validation triggers (advisory, client-side), keyed by trigger name */
-    triggers: z.record(z.string(), TriggerDefinition).optional(),
-    /**
-     * DocBuilder node positions keyed by state name — authoring view-state. Persisted here so a
-     * doctype author's manual graph arrangement survives reloads; like `triggers`, it is client-only
-     * and never enters the runtime GraphQL SDL. See {@link (WorkflowLayout:variable)}.
-     */
-    layout: WorkflowLayout.optional(),
-})
-    .meta({
-    title: 'WorkflowMeta',
-    description: 'Workflow metadata - states and actions for a doctype',
-});
-/**
- * Doctype metadata - complete definition of a doctype
- * @public
- */
-export const DoctypeMeta = z
-    .object({
-    /** Display name of the doctype */
-    name: z.string().min(1),
-    /** URL-friendly slug (kebab-case) */
-    slug: z.string().min(1).optional(),
-    /**
-     * Field on this doctype used when displaying a reference to one of its records.
-     * When a record elsewhere holds an inline foreign key to this doctype, the middleware
-     * returns that field as `{ id, displayText }`, reading `displayText` from this field.
-     */
-    displayField: z.string().min(1).optional(),
-    /**
-     * URL path this doctype registers at, written literally — `/order` for a collection,
-     * `/order/:id` for a record. Absent means the doctype has no page of its own, which is the
-     * common case: a child table is reached inside its parent, never at a URL.
-     *
-     * A path rather than a segment because the record parameter has to be somewhere, and a host
-     * that reads a bare segment has to know which kind of doctype it is holding to decide where
-     * to put it. Writing it out means nothing downstream re-derives it.
-     */
-    route: z.string().startsWith('/').optional(),
-    /** Field definitions (a link field is one carrying `doctype`) */
-    fields: z.array(DoctypeFieldSchema),
-    /** Relationship links to other doctypes */
-    links: z.record(z.string(), LinkDeclaration).optional(),
-    /** Workflow configuration */
-    workflow: WorkflowMeta.optional(),
-    /** Parent doctype for inheritance */
-    inherits: z.string().optional(),
-})
-    .meta({
-    title: 'DoctypeMeta',
-    description: 'Doctype metadata - complete definition of a doctype',
-})
-    .superRefine((doctype, ctx) => {
-    // A record is identified by exactly one field here, and that is the design rather than a
-    // limitation awaiting composite support. A doctype describes the **API surface** a client
-    // interacts with, not the table behind it; how a composite database key maps onto a single
-    // identity on that surface is the server's business, and the client neither sees nor
-    // encodes the parts. So there is nothing for a doctype-level composite key to express.
-    //
-    // Declaring several is therefore malformed, and silently so: `getPrimaryKeyField` takes the
-    // first match and the rest are ignored, leaving an adapter to key records on a column that
-    // need not be unique — `stonecropRecord`'s row map then keeps whichever row comes last.
-    // Refusing at the gate is what makes it say so.
-    //
-    // Counts the flattened set, because that is the set `getPrimaryKeyField` resolves over. The
-    // two asked different questions while this scanned top level only: a doctype with one key
-    // declared at each level passed the gate and then had one of them silently dropped.
-    //
-    // Zero keys stays legal and is not an omission: a surrogate-key doctype declares none and
-    // resolves through `getRecordIdField`'s documented `id` fallback.
-    const declared = flattenFields(doctype.fields).filter(f => f.kind === 'field' && f.primaryKey);
-    if (declared.length > 1) {
-        ctx.addIssue({
-            code: 'custom',
-            path: ['fields'],
-            message: `Doctype declares ${declared.length} primaryKey fields (${declared
-                .map(f => (f.kind === 'field' ? f.fieldname : ''))
-                .join(', ')}); a record is identified by exactly one field. A composite database key is mapped to a single identity by the adapter, so a doctype never declares its parts`,
-        });
-    }
-    // Through `getDisplayField` rather than a scan written here, because the adapter builds its
-    // SELECT from that same call. The two hand-rolled versions disagreed in both directions at
-    // once: this gate scanned top-level only, so it rejected a fieldset-nested field that would
-    // have worked, while neither side excluded `computed` fields, so a nomination naming one
-    // passed the gate and then failed as a missing column at query time.
-    if (doctype.displayField && !getDisplayField(doctype.fields, doctype.displayField)) {
-        const named = flattenFields(doctype.fields).find(f => f.fieldname === doctype.displayField);
-        ctx.addIssue({
-            code: 'custom',
-            path: ['displayField'],
-            message: named
-                ? `displayField "${doctype.displayField}" names a computed field, which has no column to read a display value from`
-                : `displayField "${doctype.displayField}" is not declared on this doctype`,
-        });
-    }
-});
-/**
- * The one string a doctype is addressed by.
- *
- * A doctype carries two names — `name` (`OrderItem`) and `slug` (`order-item`) — and every registry
- * must agree on which one keys it. Three implementations had drifted apart: the adapter's registry is
- * keyed by `name` and its `getMeta` also scans for a matching `slug`, so it accepts **either**; the
- * client's registry is keyed by a slug it derives itself and accepts **only** that; and
- * `Doctype.fromObject` dropped an authored `slug` on the floor and re-derived one regardless. The
- * adapter's accepted set was therefore a strict superset of the client's, and a link target written
- * as the Name booted the server, passed its reference check, served rows over GraphQL, and was
- * silently dropped by the client — an expanding child table rendering as one empty text input, with
- * nothing logged.
- *
- * Resolving through this in both runtimes is what makes the two answers the same answer. It is the
- * derivation only; a *lookup* still belongs to whichever registry owns the corpus, because the two
- * corpora legitimately differ (a client registers lazily, and a client-only host has no adapter at
- * all).
- *
- * An authored `slug` wins over the derived one because the authored doctype is the source of truth:
- * generation verifies a file and never overwrites it, so a doctype that states its own slug means it.
- * Deriving unconditionally is what `fromObject` did, and it made an authored `slug` a silent no-op on
- * one side of the wire while the other honoured it.
- *
- * @param doctype - anything carrying a doctype's `name` and optional authored `slug`
- * @returns the canonical slug
- * @public
- *
- * @example
- * ```typescript
- * getDoctypeSlug({ name: 'OrderItem' })                      // 'order-item'
- * getDoctypeSlug({ name: 'Planner', slug: 'planner-board' }) // 'planner-board'
- * ```
- */
-export function getDoctypeSlug(doctype) {
-    // `||` rather than `??`: an empty authored slug is not a usable registry key, and this is
-    // reachable — `Doctype.fromObject` builds a doctype without going through the Zod gate, which is
-    // where `slug: z.string().min(1)` would have refused it.
-    return doctype.slug || toSlug(doctype.name);
-}
-/**
- * Suffix appended to a link fieldname for its pre-resolved display text in record payloads.
- *
- * @deprecated The `__display` suffix pattern is no longer used. Inline link fields are enriched
- * server-side by `@stonecrop/graphql-middleware` as `{ id, displayText }` objects on the link
- * field itself.
- * @public
- */
-export const LINK_DISPLAY_SUFFIX = '__display';
-/**
- * Build the payload key for a link field's display text (e.g. `customerId__display`).
- *
- * @deprecated The `__display` suffix pattern is no longer used. Inline link fields are enriched
- * server-side by `@stonecrop/graphql-middleware` as `{ id, displayText }` objects on the link
- * field itself.
- * @public
- */
-export function linkDisplayFieldname(fieldname) {
-    return `${fieldname}${LINK_DISPLAY_SUFFIX}`;
-}