@stonecrop/schema 0.10.16 → 0.11.1

package/README.md

@@ -86,7 +86,7 @@ const decimalField: FieldMeta = {
 
 ### Doctype Metadata
 
-`DoctypeMeta` defines a complete doctype with fields, workflow, and inheritance:
+`DoctypeMeta` defines a complete doctype with fields, links, workflow, and inheritance:
 
 ```typescript
 import { DoctypeMeta } from '@stonecrop/schema'
@@ -105,11 +105,19 @@ const doctype: DoctypeMeta = {
     },
     {
       fieldname: 'items',
-      fieldtype: 'Doctype',
-      label: 'Order Items',
-      options: 'sales-order-item', // Child doctype
+      fieldtype: 'Link',
+      label: 'Items',
+      options: 'sales-order-item',
     },
   ],
+  links: {
+    items: {
+      target: 'sales-order-item',
+      cardinality: 'noneOrMany',
+      backlink: 'sales_order',
+      fieldname: 'items',
+    },
+  },
   workflow: {
     states: ['Draft', 'Submitted', 'Cancelled'],
     actions: {
@@ -124,6 +132,35 @@ const doctype: DoctypeMeta = {
 }
 ```
 
+### Link Declarations
+
+`links` on `DoctypeMeta` declares relationships to other doctypes. Each link has a `target`, `cardinality`, and optional `backlink`:
+
+```typescript
+import { LinkDeclaration, Cardinality } from '@stonecrop/schema'
+
+// Cardinality values:
+// 'one'         — exactly 1 (required pointer)
+// 'atMostOne'   — 0 or 1 (optional pointer)
+// 'noneOrMany'  — 0 or more (optional collection)
+// 'atLeastOne'  — 1 or more (required collection)
+
+const links: Record<string, LinkDeclaration> = {
+  // 1:many — ancestor has descendants
+  tasks: {
+    target: 'recipe-task',
+    cardinality: 'noneOrMany',
+    backlink: 'recipe', // fieldname on recipe-task that points back
+  },
+  // Self-referential — version lineage
+  supersededBy: {
+    target: 'recipe',
+    cardinality: 'atMostOne',
+    backlink: 'supersededBy',
+  },
+}
+```
+
 ### Workflow and Actions
 
 Define state machines and actions for doctypes:
@@ -151,6 +188,36 @@ const workflow: WorkflowMeta = {
 }
 ```
 
+## Client Interfaces
+
+`DataClient` is the interface that any data transport must implement. `GetRecordOptions` and `GetRecordsOptions` are the option types:
+
+```typescript
+import type { DataClient, GetRecordOptions, GetRecordsOptions } from '@stonecrop/schema'
+
+// Fetch a record — with optional nested link sub-selections
+const record = await client.getRecord({ name: 'Recipe' }, 'r1', {
+  includeNested: true, // fetch all descendant links
+  maxDepth: 2, // limit recursion depth
+})
+
+// Fetch only specific links
+const record = await client.getRecord({ name: 'Recipe' }, 'r1', {
+  includeNested: ['tasks'], // fetch only the tasks link
+})
+
+// Fetch multiple records
+const records = await client.getRecords(
+  { name: 'Recipe' },
+  {
+    filters: { status: 'Active' },
+    orderBy: 'name',
+    limit: 20,
+    offset: 0,
+  }
+)
+```
+
 ## Validation
 
 Runtime validation with detailed error reporting:
@@ -237,18 +304,18 @@ then `--exclude` removes any remaining unwanted names.
 
 ### All options
 
-| Flag | Short | Description |
-|------|-------|-------------|
-| `--endpoint <url>` | `-e` | Fetch introspection from a live GraphQL endpoint |
-| `--introspection <file>` | `-i` | Read from a saved introspection JSON file |
-| `--sdl <file>` | `-s` | Read from a GraphQL SDL (`.graphql`) file |
-| `--output <dir>` | `-o` | Directory to write doctype JSON files (required) |
-| `--include <types>` | | Comma-separated allowlist of type names to generate |
-| `--exclude <types>` | | Comma-separated list of type names to skip |
-| `--overrides <file>` | | JSON file with per-type, per-field overrides |
-| `--custom-scalars <file>` | | JSON file mapping custom scalar names to field templates |
-| `--include-unmapped` | | Retain `_graphqlType` metadata on fields with no mapping |
-| `--help` | `-h` | Show help |
+| Flag                      | Short | Description                                              |
+| ------------------------- | ----- | -------------------------------------------------------- |
+| `--endpoint <url>`        | `-e`  | Fetch introspection from a live GraphQL endpoint         |
+| `--introspection <file>`  | `-i`  | Read from a saved introspection JSON file                |
+| `--sdl <file>`            | `-s`  | Read from a GraphQL SDL (`.graphql`) file                |
+| `--output <dir>`          | `-o`  | Directory to write doctype JSON files (required)         |
+| `--include <types>`       |       | Comma-separated allowlist of type names to generate      |
+| `--exclude <types>`       |       | Comma-separated list of type names to skip               |
+| `--overrides <file>`      |       | JSON file with per-type, per-field overrides             |
+| `--custom-scalars <file>` |       | JSON file mapping custom scalar names to field templates |
+| `--include-unmapped`      |       | Retain `_graphqlType` metadata on fields with no mapping |
+| `--help`                  | `-h`  | Show help                                                |
 
 ### Custom scalars
 
@@ -258,7 +325,7 @@ a JSON mapping file:
 ```json
 {
   "BigFloat": { "component": "ADecimalInput", "fieldtype": "Decimal" },
-  "Datetime":  { "component": "ADatetimeInput", "fieldtype": "Datetime" }
+  "Datetime": { "component": "ADatetimeInput", "fieldtype": "Datetime" }
 }
 ```
 
@@ -332,14 +399,7 @@ doctypes.forEach(doctype => {
 Convert between different naming conventions:
 
 ```typescript
-import {
-  snakeToCamel,
-  camelToSnake,
-  snakeToLabel,
-  camelToLabel,
-  toPascalCase,
-  toSlug,
-} from '@stonecrop/schema'
+import { snakeToCamel, camelToSnake, snakeToLabel, camelToLabel, toPascalCase, toSlug } from '@stonecrop/schema'
 
 snakeToCamel('customer_name') // 'customerName'
 camelToSnake('customerName') // 'customer_name'
@@ -367,7 +427,8 @@ console.log(TYPE_MAP['Link']) // { component: 'ALink', fieldtype: 'Link' }
 
 This package provides the type system used throughout Stonecrop:
 
-- **`@stonecrop/stonecrop`** - Registry uses `DoctypeMeta` for schema storage
+- **`@stonecrop/stonecrop`** - Registry uses `DoctypeMeta` for schema storage; `getDescendantLinks()` / `getAncestorLinks()` for relationship traversal
+- **`@stonecrop/graphql-client`** - `StonecropClient` implements `DataClient`; uses `GetRecordOptions` / `GetRecordsOptions` for fetch parameters
 - **`@stonecrop/aform`** - Renders fields based on `FieldMeta` definitions
 - **`@stonecrop/atable`** - Uses `FieldMeta` for column configuration
 - **Backend APIs** - Validates and stores doctypes using these schemas

package/dist/cli.js

@@ -3,7 +3,7 @@ import { readFileSync as u, existsSync as S, mkdirSync as w, writeFileSync as x
 import { resolve as c, join as O } from "node:path";
 import { parseArgs as $ } from "node:util";
 import { getIntrospectionQuery as N } from "graphql";
-import { h as P, v as j } from "./index-D6Up-BP5.js";
+import { e as P, v as j } from "./index-CLc5mUMQ.js";
 async function C(e, m) {
   const t = await fetch(e, {
     method: "POST",

package/dist/converter/heuristics.js

@@ -223,21 +223,23 @@ export function classifyFieldType(fieldName, field, entityTypes, options = {}) {
             base.options = toSlug(namedType.name);
             return base;
         }
-        // 4. Connection type → Doctype (child table)
+        // 4. Connection type → link (child table)
         const connectionNodeTypeName = getConnectionNodeType(namedType);
         if (connectionNodeTypeName && entityTypes.has(connectionNodeTypeName)) {
             base.component = 'ATable';
-            base.fieldtype = 'Doctype';
+            base._isLink = true;
             base.options = toSlug(connectionNodeTypeName);
-            base.cardinality = 'many';
+            base.cardinality = 'noneOrMany';
+            delete base.fieldtype;
             return base;
         }
-        // 5. List of entity type → Doctype
+        // 5. List of entity type → link
         if (isList && entityTypes.has(namedType.name)) {
             base.component = 'ATable';
-            base.fieldtype = 'Doctype';
+            base._isLink = true;
             base.options = toSlug(namedType.name);
-            base.cardinality = 'many';
+            base.cardinality = 'noneOrMany';
+            delete base.fieldtype;
             return base;
         }
         // Unknown object type — mark as unmapped

package/dist/converter/index.js

@@ -88,7 +88,7 @@ export function convertGraphQLSchema(source, options = {}) {
             continue;
         const fields = type.getFields();
         const typeOverrides = options.typeOverrides?.[typeName];
-        const convertedFields = Object.entries(fields)
+        const allClassifiedFields = Object.entries(fields)
             .filter(([fieldName, field]) => isEntityField(fieldName, field, type))
             .map(([fieldName, field]) => {
             // Check for full custom classification first
@@ -111,20 +111,37 @@ export function convertGraphQLSchema(source, options = {}) {
                 return { ...classified, ...typeOverrides[fieldName] };
             }
             return classified;
+        });
+        // Separate scalar fields from link fields
+        const links = {};
+        const convertedFields = allClassifiedFields
+            .filter(field => {
+            if (field._isLink && typeof field.options === 'string' && field.cardinality) {
+                links[field.fieldname] = {
+                    target: field.options,
+                    cardinality: field.cardinality,
+                };
+                return false;
+            }
+            return true;
         })
             // Clean up internal metadata unless requested
             .map(field => {
             if (!options.includeUnmappedMeta) {
-                const { _graphqlType, _unmapped, ...clean } = field;
+                const { _graphqlType, _unmapped, _isLink, ...clean } = field;
                 return clean;
             }
-            return field;
+            const { _isLink, ...rest } = field;
+            return rest;
         });
         const doctype = {
             name: typeName,
             slug: toSlug(typeName),
             fields: convertedFields,
         };
+        if (Object.keys(links).length > 0) {
+            doctype.links = links;
+        }
         const tableName = deriveTableName(typeName);
         if (tableName) {
             doctype.tableName = tableName;

package/dist/doctype.js

@@ -1,5 +1,92 @@
 import { z } from 'zod';
 import { FieldMeta } from './field';
+/**
+ * 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
@@ -50,16 +137,14 @@ export const DoctypeMeta = z
     slug: z.string().min(1).optional(),
     /** Database table name */
     tableName: z.string().optional(),
-    /** Field definitions */
+    /** Field definitions (including link fields with fieldtype: 'Link') */
     fields: z.array(FieldMeta),
+    /** 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(),
-    /** Doctype to use for list views */
-    listDoctype: z.string().optional(),
-    /** Parent doctype for child tables */
-    parentDoctype: z.string().optional(),
 })
     .meta({
     title: 'DoctypeMeta',

package/dist/field.js

@@ -85,10 +85,12 @@ export const FieldMeta = z
     options: FieldOptions.optional(),
     /**
      * Cardinality for Doctype fields:
-     * - 'one': 1:1 nested form (default)
-     * - 'many': 1:many child table
+     * - 'one': exactly 1 (default)
+     * - 'atMostOne': 0 or 1
+     * - 'noneOrMany': 0 or more
+     * - 'atLeastOne': 1 or more
      */
-    cardinality: z.enum(['one', 'many']).optional(),
+    cardinality: z.enum(['one', 'atMostOne', 'noneOrMany', 'atLeastOne']).optional(),
     /**
      * Input mask pattern. Accepts either a plain mask string or a stringified
      * arrow function that receives `locale` and returns a mask string.

package/dist/fieldtype.js

@@ -20,7 +20,6 @@ export const StonecropFieldType = z
     'JSON', // JSON data
     'Code', // Code/source (with syntax highlighting)
     'Link', // Reference to another doctype
-    'Doctype', // Child doctype (1:1 nested form or 1:many table via cardinality)
     'Attach', // File attachment
     'Currency', // Currency value
     'Quantity', // Quantity with unit
@@ -56,7 +55,6 @@ export const TYPE_MAP = {
     Code: { component: 'ACodeEditor', fieldtype: 'Code' },
     // Relational
     Link: { component: 'ALink', fieldtype: 'Link' },
-    Doctype: { component: 'AForm', fieldtype: 'Doctype' },
     // Files
     Attach: { component: 'AFileAttach', fieldtype: 'Attach' },
     // Specialized