@stonecrop/schema 0.8.5 → 0.8.7

package/README.md

@@ -0,0 +1,329 @@
+# @stonecrop/schema
+
+Schema definitions and validation for Stonecrop doctypes, fields, and workflows.
+
+## Overview
+
+`@stonecrop/schema` provides the foundational type system for Stonecrop applications. It defines strongly-typed schemas using [Zod](https://zod.dev/) for:
+
+- **Field definitions** (`FieldMeta`) - Unified field configuration for forms and tables
+- **Doctype definitions** (`DoctypeMeta`) - Complete document type schemas
+- **Workflows** (`WorkflowMeta`) - State machines and action definitions
+- **Validation** - Runtime schema validation with detailed error reporting
+- **DDL Conversion** - PostgreSQL DDL to Stonecrop schema transformation
+
+This package is schema-only and has no UI dependencies - it can be used in both frontend and backend contexts.
+
+## Installation
+
+```bash
+# From the monorepo root
+rush update
+
+# Or with pnpm
+pnpm add @stonecrop/schema
+```
+
+## Core Concepts
+
+### Field Types
+
+Stonecrop uses semantic field types that remain consistent whether rendered in a form or table:
+
+```typescript
+import { StonecropFieldType, FieldMeta } from '@stonecrop/schema'
+
+// Field types include:
+// Text: Data, Text
+// Numeric: Int, Float, Decimal, Currency, Quantity
+// Boolean: Check
+// Date/Time: Date, Time, Datetime, Duration, DateRange
+// Structured: JSON, Code
+// Relational: Link, Doctype
+// Files: Attach
+// Selection: Select
+```
+
+### Field Metadata
+
+`FieldMeta` is the single source of truth for field definitions:
+
+```typescript
+import { FieldMeta } from '@stonecrop/schema'
+
+const field: FieldMeta = {
+  fieldname: 'customer_name',
+  fieldtype: 'Data',
+  label: 'Customer Name',
+  required: true,
+  readOnly: false,
+  width: '40ch',
+  align: 'left',
+}
+
+// Type-specific options
+const linkField: FieldMeta = {
+  fieldname: 'customer',
+  fieldtype: 'Link',
+  label: 'Customer',
+  options: 'customer', // Target doctype slug
+}
+
+const selectField: FieldMeta = {
+  fieldname: 'status',
+  fieldtype: 'Select',
+  label: 'Status',
+  options: ['Draft', 'Submitted', 'Cancelled'], // Choices array
+}
+
+const decimalField: FieldMeta = {
+  fieldname: 'price',
+  fieldtype: 'Decimal',
+  label: 'Price',
+  options: { precision: 10, scale: 2 }, // Config object
+}
+```
+
+### Doctype Metadata
+
+`DoctypeMeta` defines a complete doctype with fields, workflow, and inheritance:
+
+```typescript
+import { DoctypeMeta } from '@stonecrop/schema'
+
+const doctype: DoctypeMeta = {
+  name: 'Sales Order',
+  slug: 'sales-order',
+  tableName: 'sales_order',
+  fields: [
+    {
+      fieldname: 'customer',
+      fieldtype: 'Link',
+      label: 'Customer',
+      options: 'customer',
+      required: true,
+    },
+    {
+      fieldname: 'items',
+      fieldtype: 'Doctype',
+      label: 'Order Items',
+      options: 'sales-order-item', // Child doctype
+    },
+  ],
+  workflow: {
+    states: ['Draft', 'Submitted', 'Cancelled'],
+    actions: {
+      submit: {
+        label: 'Submit',
+        handler: 'submitOrder',
+        requiredFields: ['customer', 'items'],
+        allowedStates: ['Draft'],
+      },
+    },
+  },
+}
+```
+
+### Workflow and Actions
+
+Define state machines and actions for doctypes:
+
+```typescript
+import { WorkflowMeta, ActionDefinition } from '@stonecrop/schema'
+
+const workflow: WorkflowMeta = {
+  states: ['Draft', 'Pending Approval', 'Approved', 'Rejected'],
+  actions: {
+    submit: {
+      label: 'Submit for Approval',
+      handler: 'handleSubmit',
+      requiredFields: ['title', 'description'],
+      allowedStates: ['Draft'],
+      confirm: true,
+    },
+    approve: {
+      label: 'Approve',
+      handler: 'handleApprove',
+      allowedStates: ['Pending Approval'],
+      args: { notifyUser: true },
+    },
+  },
+}
+```
+
+## Validation
+
+Runtime validation with detailed error reporting:
+
+```typescript
+import { validateField, validateDoctype } from '@stonecrop/schema'
+
+// Validate a field definition
+const fieldResult = validateField({
+  fieldname: 'email',
+  fieldtype: 'Data',
+  label: 'Email',
+})
+
+if (!fieldResult.success) {
+  console.error('Validation errors:', fieldResult.errors)
+  // errors: [{ path: ['fieldname'], message: 'Required' }]
+}
+
+// Validate a doctype definition
+const doctypeResult = validateDoctype(doctypeData)
+
+if (doctypeResult.success) {
+  console.log('Doctype is valid!')
+}
+```
+
+### Parse and Validate
+
+Use Zod's parse methods for type-safe validation:
+
+```typescript
+import { parseField, parseDoctype } from '@stonecrop/schema'
+
+try {
+  const field = parseField(untrustedData)
+  // TypeScript knows field is FieldMeta
+} catch (error) {
+  console.error('Invalid field:', error)
+}
+
+try {
+  const doctype = parseDoctype(untrustedData)
+  // TypeScript knows doctype is DoctypeMeta
+} catch (error) {
+  console.error('Invalid doctype:', error)
+}
+```
+
+## DDL Conversion
+
+Convert PostgreSQL DDL statements to Stonecrop doctype schemas:
+
+```typescript
+import { convertSchema, type ConversionOptions } from '@stonecrop/schema'
+
+const ddl = `
+CREATE TABLE customers (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR(255) NOT NULL,
+  email VARCHAR(255) UNIQUE,
+  created_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE TABLE sales_orders (
+  id SERIAL PRIMARY KEY,
+  customer_id INTEGER REFERENCES customers(id),
+  status VARCHAR(20) DEFAULT 'Draft',
+  total_amount DECIMAL(10, 2)
+);
+`
+
+const options: ConversionOptions = {
+  inheritanceMode: 'flatten', // or 'reference'
+  useCamelCase: true, // Convert snake_case to camelCase
+  includeUnmappedMeta: false, // Include unmapped metadata
+  schema: 'public', // Filter by schema
+  exclude: ['migrations'], // Exclude tables
+  typeOverrides: {
+    status: { fieldtype: 'Select', options: ['Draft', 'Submitted'] },
+  },
+}
+
+const doctypes = convertSchema(ddl, options)
+
+doctypes.forEach(doctype => {
+  console.log(`Doctype: ${doctype.name}`)
+  console.log(`Table: ${doctype.tableName}`)
+  console.log(`Fields: ${doctype.fields.length}`)
+})
+```
+
+### Naming Utilities
+
+Convert between different naming conventions:
+
+```typescript
+import {
+  snakeToCamel,
+  camelToSnake,
+  snakeToLabel,
+  camelToLabel,
+  toPascalCase,
+  toSlug,
+} from '@stonecrop/schema'
+
+snakeToCamel('customer_name') // 'customerName'
+camelToSnake('customerName') // 'customer_name'
+snakeToLabel('customer_name') // 'Customer Name'
+camelToLabel('customerName') // 'Customer Name'
+toPascalCase('customer_name') // 'CustomerName'
+toSlug('Customer Name') // 'customer-name'
+```
+
+## API
+
+### Field Type Mapping
+
+```typescript
+import { TYPE_MAP, getDefaultComponent } from '@stonecrop/schema'
+
+// Get default component for a field type
+const component = getDefaultComponent('Data') // 'ATextInput'
+
+// Access full type map
+console.log(TYPE_MAP['Link']) // { component: 'ALink', fieldtype: 'Link' }
+```
+
+## Usage in Stonecrop
+
+This package provides the type system used throughout Stonecrop:
+
+- **`@stonecrop/stonecrop`** - Registry uses `DoctypeMeta` for schema storage
+- **`@stonecrop/aform`** - Renders fields based on `FieldMeta` definitions
+- **`@stonecrop/atable`** - Uses `FieldMeta` for column configuration
+- **Backend APIs** - Validates and stores doctypes using these schemas
+
+## Development
+
+```bash
+# Install dependencies
+rush update
+
+# Build
+rushx build
+
+# Run tests
+rushx test
+
+# Watch mode
+rushx test:watch
+
+# Generate API documentation
+rushx docs
+```
+
+## TypeScript Support
+
+This package is written in TypeScript with strict mode enabled and provides full type definitions:
+
+```typescript
+import type { FieldMeta, DoctypeMeta } from '@stonecrop/schema'
+
+// Types are inferred from Zod schemas
+const field: FieldMeta = {
+  fieldname: 'title',
+  fieldtype: 'Data',
+  // TypeScript will catch typos and missing required fields
+}
+
+// Use Zod's infer utility for derived types
+import { z } from 'zod'
+import { FieldMeta as FieldMetaSchema } from '@stonecrop/schema'
+
+type FieldMetaType = z.infer<typeof FieldMetaSchema>
+```

package/dist/cli.cjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+"use strict";const r=require("node:fs"),c=require("node:path"),w=require("node:util"),x=require("graphql"),v=require("./index-aeXXzPET.cjs");async function O(e,h){const t=await fetch(e,{method:"POST",headers:{"Content-Type":"application/json",...h},body:JSON.stringify({query:x.getIntrospectionQuery()})});if(!t.ok)throw new Error(`Failed to fetch introspection: ${t.status} ${t.statusText}`);const a=await t.json();if(a.errors?.length)throw new Error(`GraphQL errors: ${a.errors.map(n=>n.message).join(", ")}`);if(!a.data)throw new Error("No data in introspection response");return a.data}async function $(){const{values:e,positionals:h}=w.parseArgs({allowPositionals:!0,options:{endpoint:{type:"string",short:"e"},introspection:{type:"string",short:"i"},sdl:{type:"string",short:"s"},output:{type:"string",short:"o"},include:{type:"string"},exclude:{type:"string"},overrides:{type:"string"},"custom-scalars":{type:"string"},"include-unmapped":{type:"boolean",default:!1},help:{type:"boolean",short:"h"}}}),t=h[0];(e.help||!t)&&(q(),process.exit(t?0:1)),t!=="generate"&&(console.error(`Unknown command: ${t}`),console.error("Available commands: generate"),process.exit(1)),[e.endpoint,e.introspection,e.sdl].filter(Boolean).length!==1&&(console.error("Exactly one of --endpoint, --introspection, or --sdl must be provided"),process.exit(1)),e.output||(console.error("--output <dir> is required"),process.exit(1));const n=c.resolve(e.output),l={includeUnmappedMeta:e["include-unmapped"]};if(e.include&&(l.include=e.include.split(",").map(o=>o.trim())),e.exclude&&(l.exclude=e.exclude.split(",").map(o=>o.trim())),e.overrides){const o=c.resolve(e.overrides),s=r.readFileSync(o,"utf-8");l.typeOverrides=JSON.parse(s)}if(e["custom-scalars"]){const o=c.resolve(e["custom-scalars"]),s=r.readFileSync(o,"utf-8");l.customScalars=JSON.parse(s)}let p;if(e.endpoint)console.log(`Fetching introspection from ${e.endpoint}...`),p=await O(e.endpoint);else if(e.introspection){const o=c.resolve(e.introspection),s=r.readFileSync(o,"utf-8"),u=JSON.parse(s);p=u.data??u}else{const o=c.resolve(e.sdl);p=r.readFileSync(o,"utf-8")}const m=v.convertGraphQLSchema(p,l);m.length===0&&(console.warn("No entity types found in the schema. Check your include/exclude filters."),process.exit(0)),r.existsSync(n)||r.mkdirSync(n,{recursive:!0});let f=0,d=0;for(const o of m){const s=`${o.slug}.json`,u=c.join(n,s),S=JSON.stringify(o,null,"	");r.writeFileSync(u,S+`
+`,"utf-8");const g=v.validateDoctype(o);if(g.success){const i=o.fields.filter(y=>y._unmapped);i.length>0&&(f++,console.warn(`  WARN: ${s} has ${i.length} unmapped field(s): ${i.map(y=>y.fieldname).join(", ")}`))}else{d++,console.error(`  ERROR: ${s} failed validation:`);for(const i of g.errors)console.error(`    ${i.path.join(".")}: ${i.message}`)}}console.log(`
+Generated ${m.length} doctype(s) in ${n}`+(f?` (${f} with warnings)`:"")+(d?` (${d} with errors)`:"")),d>0&&process.exit(1)}function q(){console.log(`
+stonecrop-schema - Convert GraphQL schemas to Stonecrop doctypes
+
+USAGE:
+  stonecrop-schema generate [options]
+
+SOURCE (exactly one required):
+  --endpoint, -e <url>         Fetch introspection from a live GraphQL endpoint
+  --introspection, -i <file>   Read from a saved introspection JSON file
+  --sdl, -s <file>             Read from a GraphQL SDL (.graphql) file
+
+OUTPUT:
+  --output, -o <dir>           Directory to write doctype JSON files (required)
+
+OPTIONS:
+  --include <types>            Comma-separated list of type names to include
+  --exclude <types>            Comma-separated list of type names to exclude
+  --overrides <file>           JSON file with per-type field overrides
+  --custom-scalars <file>      JSON file mapping custom scalar names to field templates
+  --include-unmapped           Include _graphqlType metadata on unmapped fields
+  --help, -h                   Show this help message
+
+EXAMPLES:
+  # From a live PostGraphile server
+  stonecrop-schema generate -e http://localhost:5000/graphql -o ./schemas
+
+  # From a saved introspection result
+  stonecrop-schema generate -i introspection.json -o ./schemas
+
+  # From an SDL file with custom scalars
+  stonecrop-schema generate -s schema.graphql -o ./schemas \\
+    --custom-scalars custom-scalars.json
+
+  # Only convert specific types
+  stonecrop-schema generate -e http://localhost:5000/graphql -o ./schemas \\
+    --include "User,Post,Comment"
+`)}$().catch(e=>{console.error("Error:",e.message),process.exit(1)});

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export { }

package/dist/cli.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+import { readFileSync as u, existsSync as S, mkdirSync as w, writeFileSync as x } from "node:fs";
+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-COrltkHl.js";
+async function C(e, m) {
+  const t = await fetch(e, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      ...m
+    },
+    body: JSON.stringify({
+      query: N()
+    })
+  });
+  if (!t.ok)
+    throw new Error(`Failed to fetch introspection: ${t.status} ${t.statusText}`);
+  const i = await t.json();
+  if (i.errors?.length)
+    throw new Error(`GraphQL errors: ${i.errors.map((r) => r.message).join(", ")}`);
+  if (!i.data)
+    throw new Error("No data in introspection response");
+  return i.data;
+}
+async function E() {
+  const { values: e, positionals: m } = $({
+    allowPositionals: !0,
+    options: {
+      endpoint: { type: "string", short: "e" },
+      introspection: { type: "string", short: "i" },
+      sdl: { type: "string", short: "s" },
+      output: { type: "string", short: "o" },
+      include: { type: "string" },
+      exclude: { type: "string" },
+      overrides: { type: "string" },
+      "custom-scalars": { type: "string" },
+      "include-unmapped": { type: "boolean", default: !1 },
+      help: { type: "boolean", short: "h" }
+    }
+  }), t = m[0];
+  (e.help || !t) && (q(), process.exit(t ? 0 : 1)), t !== "generate" && (console.error(`Unknown command: ${t}`), console.error("Available commands: generate"), process.exit(1)), [e.endpoint, e.introspection, e.sdl].filter(Boolean).length !== 1 && (console.error("Exactly one of --endpoint, --introspection, or --sdl must be provided"), process.exit(1)), e.output || (console.error("--output <dir> is required"), process.exit(1));
+  const r = c(e.output), a = {
+    includeUnmappedMeta: e["include-unmapped"]
+  };
+  if (e.include && (a.include = e.include.split(",").map((o) => o.trim())), e.exclude && (a.exclude = e.exclude.split(",").map((o) => o.trim())), e.overrides) {
+    const o = c(e.overrides), s = u(o, "utf-8");
+    a.typeOverrides = JSON.parse(s);
+  }
+  if (e["custom-scalars"]) {
+    const o = c(e["custom-scalars"]), s = u(o, "utf-8");
+    a.customScalars = JSON.parse(s);
+  }
+  let l;
+  if (e.endpoint)
+    console.log(`Fetching introspection from ${e.endpoint}...`), l = await C(e.endpoint);
+  else if (e.introspection) {
+    const o = c(e.introspection), s = u(o, "utf-8"), d = JSON.parse(s);
+    l = d.data ?? d;
+  } else {
+    const o = c(e.sdl);
+    l = u(o, "utf-8");
+  }
+  const f = P(l, a);
+  f.length === 0 && (console.warn("No entity types found in the schema. Check your include/exclude filters."), process.exit(0)), S(r) || w(r, { recursive: !0 });
+  let h = 0, p = 0;
+  for (const o of f) {
+    const s = `${o.slug}.json`, d = O(r, s), v = JSON.stringify(o, null, "	");
+    x(d, v + `
+`, "utf-8");
+    const g = j(o);
+    if (g.success) {
+      const n = o.fields.filter((y) => y._unmapped);
+      n.length > 0 && (h++, console.warn(
+        `  WARN: ${s} has ${n.length} unmapped field(s): ${n.map((y) => y.fieldname).join(", ")}`
+      ));
+    } else {
+      p++, console.error(`  ERROR: ${s} failed validation:`);
+      for (const n of g.errors)
+        console.error(`    ${n.path.join(".")}: ${n.message}`);
+    }
+  }
+  console.log(
+    `
+Generated ${f.length} doctype(s) in ${r}` + (h ? ` (${h} with warnings)` : "") + (p ? ` (${p} with errors)` : "")
+  ), p > 0 && process.exit(1);
+}
+function q() {
+  console.log(`
+stonecrop-schema - Convert GraphQL schemas to Stonecrop doctypes
+
+USAGE:
+  stonecrop-schema generate [options]
+
+SOURCE (exactly one required):
+  --endpoint, -e <url>         Fetch introspection from a live GraphQL endpoint
+  --introspection, -i <file>   Read from a saved introspection JSON file
+  --sdl, -s <file>             Read from a GraphQL SDL (.graphql) file
+
+OUTPUT:
+  --output, -o <dir>           Directory to write doctype JSON files (required)
+
+OPTIONS:
+  --include <types>            Comma-separated list of type names to include
+  --exclude <types>            Comma-separated list of type names to exclude
+  --overrides <file>           JSON file with per-type field overrides
+  --custom-scalars <file>      JSON file mapping custom scalar names to field templates
+  --include-unmapped           Include _graphqlType metadata on unmapped fields
+  --help, -h                   Show this help message
+
+EXAMPLES:
+  # From a live PostGraphile server
+  stonecrop-schema generate -e http://localhost:5000/graphql -o ./schemas
+
+  # From a saved introspection result
+  stonecrop-schema generate -i introspection.json -o ./schemas
+
+  # From an SDL file with custom scalars
+  stonecrop-schema generate -s schema.graphql -o ./schemas \\
+    --custom-scalars custom-scalars.json
+
+  # Only convert specific types
+  stonecrop-schema generate -e http://localhost:5000/graphql -o ./schemas \\
+    --include "User,Post,Comment"
+`);
+}
+E().catch((e) => {
+  console.error("Error:", e.message), process.exit(1);
+});