@stonecrop/schema 0.7.0 → 0.7.1

package/dist/index.d.ts

@@ -33,6 +33,10 @@ export declare const ActionDefinition: z.ZodObject<{
     args?: Record<string, unknown> | undefined;
 }>;
 
+/**
+ * Action definition type inferred from Zod schema
+ * @public
+ */
 export declare type ActionDefinition = z.infer<typeof ActionDefinition>;
 
 /**
@@ -66,7 +70,9 @@ export declare function camelToSnake(camelCase: string): string;
  * @public
  */
 export declare interface ConversionFieldMeta extends FieldMeta {
+    /** Original PostgreSQL type (for debugging/reference) */
     _pgType?: string;
+    /** Marks fields that couldn't be automatically mapped */
     _unmapped?: boolean;
 }
 
@@ -94,11 +100,14 @@ export declare interface ConversionOptions {
  * @public
  */
 export declare interface ConvertedDoctype extends Omit<DoctypeMeta, 'fields'> {
+    /** Field definitions with optional conversion metadata */
     fields: ConversionFieldMeta[];
 }
 
 /**
  * Convert PostgreSQL DDL to Stonecrop doctype schemas
+ * @param sql - PostgreSQL DDL statements to convert
+ * @param options - Conversion options for controlling output format
  * @public
  */
 export declare function convertSchema(sql: string, options?: ConversionOptions): ConvertedDoctype[];
@@ -347,6 +356,10 @@ declare const DoctypeMeta: z.ZodObject<{
     parentDoctype?: string | undefined;
 }>;
 
+/**
+ * Doctype metadata type inferred from Zod schema
+ * @public
+ */
 declare type DoctypeMeta = z.infer<typeof DoctypeMeta>;
 export { DoctypeMeta }
 export { DoctypeMeta as DoctypeMetaType }
@@ -389,8 +402,8 @@ declare const FieldMeta: z.ZodObject<{
      * - Link: target doctype slug ("customer")
      * - Doctype: child doctype slug ("sales-order-item")
      * - Select: choices array (["Draft", "Submitted"])
-     * - Decimal: { precision, scale }
-     * - Code: { language }
+     * - Decimal: \{ precision, scale \}
+     * - Code: \{ language \}
      */
     options: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
     /** Input mask pattern (e.g., "##/##/####" for dates) */
@@ -446,6 +459,10 @@ declare const FieldMeta: z.ZodObject<{
     mask?: string | undefined;
 }>;
 
+/**
+ * Field metadata type inferred from Zod schema
+ * @public
+ */
 declare type FieldMeta = z.infer<typeof FieldMeta>;
 export { FieldMeta }
 export { FieldMeta as FieldMetaType }
@@ -456,22 +473,31 @@ export { FieldMeta as FieldMetaType }
  * Usage by fieldtype:
  * - Link/Doctype: target doctype slug as string ("customer", "sales-order-item")
  * - Select: array of choices (["Draft", "Submitted", "Cancelled"])
- * - Decimal: config object ({ precision: 10, scale: 2 })
- * - Code: config object ({ language: "python" })
+ * - Decimal: config object (\{ precision: 10, scale: 2 \})
+ * - Code: config object (\{ language: "python" \})
  *
  * @public
  */
 declare const FieldOptions: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
 
+/**
+ * Field options type inferred from Zod schema
+ * @public
+ */
 declare type FieldOptions = z.infer<typeof FieldOptions>;
 export { FieldOptions }
 export { FieldOptions as FieldOptionsType }
 
-/* Excluded from this release type: FieldTemplate */
-
-declare interface FieldTemplate_2 {
+/**
+ * Field template for TYPE_MAP entries
+ * @public
+ */
+declare interface FieldTemplate {
     component: string;
     fieldtype: StonecropFieldType;
+}
+
+declare interface FieldTemplate_2 extends FieldTemplate {
     _unmapped?: boolean;
 }
 
@@ -490,6 +516,10 @@ export declare const FieldValidation: z.ZodObject<{
     errorMessage: z.ZodString;
 }, z.ZodTypeAny, "passthrough">>;
 
+/**
+ * Field validation type inferred from Zod schema
+ * @public
+ */
 export declare type FieldValidation = z.infer<typeof FieldValidation>;
 
 /**
@@ -513,6 +543,9 @@ export declare interface MapColumnOptions {
 
 /**
  * Map a parsed column to a Stonecrop field definition
+ * @param column - Parsed PostgreSQL column information
+ * @param _tableRegistry - Map of table names to parsed table definitions (for reference resolution)
+ * @param options - Mapping options for field naming and metadata
  * @public
  */
 export declare function mapColumnToField(column: ParsedColumn, _tableRegistry: Map<string, ParsedTable>, options?: MapColumnOptions): ConversionFieldMeta;
@@ -532,6 +565,7 @@ export declare interface NameConversion {
 
 /**
  * Normalize raw PostgreSQL type string to canonical PostgresType
+ * @param rawType - Raw PostgreSQL type string (e.g., 'character varying', 'int4')
  * @public
  */
 export declare function normalizeType(rawType: string): PostgresType;
@@ -541,26 +575,42 @@ export declare function normalizeType(rawType: string): PostgresType;
  * @public
  */
 export declare interface ParsedColumn {
+    /** Column name (from SQL definition) */
     name: string;
+    /** Raw PostgreSQL data type string */
     dataType: string;
+    /** Normalized PostgreSQL type (mapped to standard types) */
     normalizedType: PostgresType;
+    /** Whether the column allows NULL values */
     nullable: boolean;
+    /** Whether the column is auto-generated (GENERATED ALWAYS) */
     isGenerated: boolean;
+    /** Default value expression (if specified) */
     defaultValue?: string;
+    /** Number of array dimensions (0 for non-array types) */
     arrayDimensions: number;
+    /** Foreign key reference information (if column references another table) */
     reference?: {
+        /** Referenced schema name */
         schema?: string;
+        /** Referenced table name */
         table: string;
+        /** Referenced column name */
         column: string;
+        /** Foreign key ON DELETE action */
         onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
     };
+    /** Numeric precision (for NUMERIC/DECIMAL types) */
     precision?: number;
+    /** Numeric scale (for NUMERIC/DECIMAL types) */
     scale?: number;
+    /** Character/binary length constraint (for VARCHAR, CHAR, BIT types) */
     length?: number;
 }
 
 /**
  * Parse PostgreSQL DDL and extract table definitions
+ * @param sql - PostgreSQL DDL statements to parse
  * @public
  */
 export declare function parseDDL(sql: string): ParsedTable[];
@@ -579,13 +629,17 @@ export declare function parseDoctype(data: unknown): DoctypeMeta;
  * @public
  */
 export declare interface ParsedTable {
+    /** Table name (from CREATE TABLE statement) */
     name: string;
+    /** Schema name (if specified, defaults to 'public') */
     schema?: string;
+    /** Column definitions parsed from the table */
     columns: ParsedColumn[];
+    /** Parent table names (for PostgreSQL table inheritance) */
     inherits?: string[];
     /** Table comment from COMMENT ON TABLE statement */
     comment?: string;
-    /** Doctype name extracted from comment (if using @doctype convention) */
+    /** Doctype name extracted from comment (if using \@doctype convention) */
     doctypeName?: string;
 }
 
@@ -610,6 +664,10 @@ export declare const PG_TYPE_MAP: Record<PostgresType, FieldTemplate_2>;
  */
 export declare const PostgresType: z.ZodEnum<["text", "varchar", "char", "citext", "smallint", "integer", "bigint", "serial", "bigserial", "smallserial", "numeric", "decimal", "real", "double precision", "money", "boolean", "date", "time", "timetz", "timestamp", "timestamptz", "interval", "int4range", "int8range", "numrange", "daterange", "tsrange", "tstzrange", "bytea", "uuid", "json", "jsonb", "bit", "varbit", "xml", "unit", "cube", "unknown"]>;
 
+/**
+ * PostgreSQL type enum inferred from Zod schema
+ * @public
+ */
 export declare type PostgresType = z.infer<typeof PostgresType>;
 
 /**
@@ -645,6 +703,10 @@ export declare function snakeToLabel(snakeCase: string): string;
  */
 declare const StonecropFieldType: z.ZodEnum<["Data", "Text", "Int", "Float", "Decimal", "Check", "Date", "Time", "Datetime", "Duration", "DateRange", "JSON", "Code", "Link", "Doctype", "Attach", "Currency", "Quantity", "Select"]>;
 
+/**
+ * Stonecrop field type enum inferred from Zod schema
+ * @public
+ */
 declare type StonecropFieldType = z.infer<typeof StonecropFieldType>;
 export { StonecropFieldType }
 export { StonecropFieldType as StonecropFieldTypeValue }
@@ -774,6 +836,10 @@ declare const WorkflowMeta: z.ZodObject<{
     }> | undefined;
 }>;
 
+/**
+ * Workflow metadata type inferred from Zod schema
+ * @public
+ */
 declare type WorkflowMeta = z.infer<typeof WorkflowMeta>;
 export { WorkflowMeta }
 export { WorkflowMeta as WorkflowMetaType }

package/dist/index.js

@@ -76,7 +76,7 @@ const he = U.union([
   U.array(U.string()),
   // Select choices: ["A", "B", "C"]
   U.record(U.string(), U.unknown())
-  // Config: { precision: 10, scale: 2 }
+  // Config: \{ precision: 10, scale: 2 \}
 ]), xe = U.object({
   /** Error message to display when validation fails */
   errorMessage: U.string()
@@ -116,8 +116,8 @@ const he = U.union([
    * - Link: target doctype slug ("customer")
    * - Doctype: child doctype slug ("sales-order-item")
    * - Select: choices array (["Draft", "Submitted"])
-   * - Decimal: { precision, scale }
-   * - Code: { language }
+   * - Decimal: \{ precision, scale \}
+   * - Code: \{ language \}
    */
   options: he.optional(),
   /** Input mask pattern (e.g., "##/##/####" for dates) */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonecrop/schema",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -20,17 +20,22 @@
     "zod": "^3.25.76"
   },
   "devDependencies": {
+    "@rushstack/heft": "^1.1.7",
     "@types/node": "^22.19.5",
     "typescript": "^5.9.3",
     "vite": "^7.3.1",
     "vite-plugin-dts": "^4.5.4",
-    "vitest": "^4.0.17"
+    "vitest": "^4.0.17",
+    "stonecrop-rig": "0.7.0"
   },
   "scripts": {
-    "_phase:build": "vite build",
-    "prepublish": "vite build",
-    "build": "vite build",
-    "test": "vitest run",
-    "test:watch": "vitest"
+    "_phase:build": "heft build && vite build && rushx docs",
+    "prepublish": "heft build && vite build && rushx docs",
+    "build": "heft build && vite build && rushx docs",
+    "docs": "bash ../common/scripts/run-docs.sh schema",
+    "preview": "vite preview",
+    "test": "vitest run --coverage.enabled false",
+    "test:watch": "vitest watch",
+    "test:ui": "vitest --ui"
   }
 }