@stonecrop/schema 0.8.6 → 0.8.7

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+import { GraphQLField } from 'graphql';
+import { GraphQLObjectType } from 'graphql';
+import { IntrospectionQuery } from 'graphql';
 import { z } from 'zod';
 
 /**
@@ -39,6 +42,8 @@ export declare const ActionDefinition: z.ZodObject<{
  */
 export declare type ActionDefinition = z.infer<typeof ActionDefinition>;
 
+/* Excluded from this release type: buildScalarMap */
+
 /**
  * Converts camelCase to Title Case label
  * @param camelCase - Camel case string
@@ -66,88 +71,98 @@ export declare function camelToLabel(camelCase: string): string;
 export declare function camelToSnake(camelCase: string): string;
 
 /**
- * Extended field with conversion metadata (only used during schema-tools output)
- * @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;
-}
-
-/**
- * Options for DDL to doctype conversion
+ * Classify a single GraphQL field into a Stonecrop field definition.
+ *
+ * Classification rules (in order):
+ * 1. Scalar types → look up in merged scalar map
+ * 2. Enum types → `Select` with enum values as options
+ * 3. Object types that are entities → `Link` with slug as options
+ * 4. Object types that are Connections → `Doctype` with node type slug as options
+ * 5. List of entity type → `Doctype` with item type slug as options
+ * 6. Anything else → `Data` with `_unmapped: true`
+ *
+ * @param fieldName - The GraphQL field name
+ * @param field - The GraphQL field definition
+ * @param entityTypes - Set of type names classified as entities
+ * @param options - Conversion options (for custom scalars, unmapped meta, etc.)
+ * @returns The Stonecrop field definition
  * @public
  */
-export declare interface ConversionOptions {
-    /** Schema to filter tables by */
-    schema?: string;
-    /** Tables to exclude */
-    exclude?: string[];
-    /** Override type mappings */
-    typeOverrides?: Record<string, Partial<FieldMeta>>;
-    /** How to handle inherited fields */
-    inheritanceMode: 'flatten' | 'reference';
-    /** Include unmapped type metadata in output */
-    includeUnmappedMeta?: boolean;
-    /** Use camelCase for field names (default: false, keeps snake_case) */
-    useCamelCase?: boolean;
-}
+export declare function classifyFieldType(fieldName: string, field: GraphQLField<unknown, unknown>, entityTypes: Set<string>, options?: GraphQLConversionOptions): GraphQLConversionFieldMeta;
 
 /**
- * Output of schema conversion - uses DoctypeMeta but with optional conversion metadata
+ * Output of GraphQL schema conversion — one per entity type.
+ *
  * @public
  */
-export declare interface ConvertedDoctype extends Omit<DoctypeMeta, 'fields'> {
-    /** Field definitions with optional conversion metadata */
-    fields: ConversionFieldMeta[];
+export declare interface ConvertedGraphQLDoctype extends Omit<DoctypeMeta, 'fields'> {
+    /** Field definitions with optional GraphQL conversion metadata */
+    fields: GraphQLConversionFieldMeta[];
+    /** Original GraphQL type name (for debugging/reference) */
+    _graphqlTypeName?: string;
 }
 
 /**
- * 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[];
-
-/**
- * Converts SQL column name to Stonecrop field naming convention
- * Handles special cases like ID suffixes
- * @param sqlName - SQL column name (snake_case)
- * @returns Field name and label
- * @public
+ * Convert a GraphQL schema to Stonecrop doctype schemas.
+ *
+ * Accepts either an `IntrospectionQuery` result object or an SDL string.
+ * Entity types are identified using heuristics (or a custom `isEntityType` function)
+ * and converted to `DoctypeMeta`-compatible JSON objects.
+ *
+ * @param source - GraphQL introspection result or SDL string
+ * @param options - Conversion options for controlling output format and behavior
+ * @returns Array of converted Stonecrop doctype definitions
+ *
  * @example
  * ```typescript
- * convertSQLName('user_email')
- * // { fieldname: 'userEmail', label: 'User Email', originalName: 'user_email' }
+ * // From introspection result (fetched from any GraphQL server)
+ * const introspection = await fetchIntrospection('http://localhost:5000/graphql')
+ * const doctypes = convertGraphQLSchema(introspection)
+ *
+ * // From SDL string
+ * const sdl = fs.readFileSync('schema.graphql', 'utf-8')
+ * const doctypes = convertGraphQLSchema(sdl)
  *
- * convertSQLName('user_id')
- * // { fieldname: 'userId', label: 'User', originalName: 'user_id' }
+ * // With PostGraphile custom scalars
+ * const doctypes = convertGraphQLSchema(introspection, {
+ *   customScalars: {
+ *     BigFloat: { component: 'ADecimalInput', fieldtype: 'Decimal' }
+ *   }
+ * })
  * ```
+ *
+ * @public
  */
-export declare function convertSQLName(sqlName: string): NameConversion;
+export declare function convertGraphQLSchema(source: IntrospectionSource, options?: GraphQLConversionOptions): ConvertedGraphQLDoctype[];
 
 /**
- * Batch converts multiple SQL column names
- * @param sqlNames - Array of SQL column names
- * @returns Array of name conversions
+ * Default heuristic to filter fields on entity types.
+ * Skips internal fields that don't represent meaningful data.
+ *
+ * @param fieldName - The GraphQL field name
+ * @param _field - The GraphQL field definition (unused in default implementation)
+ * @param _parentType - The parent entity type (unused in default implementation)
+ * @returns `true` if this field should be included
  * @public
  */
-export declare function convertSQLNames(sqlNames: string[]): NameConversion[];
+export declare function defaultIsEntityField(fieldName: string, _field: GraphQLField<unknown, unknown>, _parentType: GraphQLObjectType): boolean;
 
 /**
- * Creates a bidirectional mapping between SQL and Stonecrop names
- * @param sqlNames - Array of SQL column names
- * @returns Mapping object with both directions
+ * Default heuristic to determine if a GraphQL object type represents an entity.
+ * An entity type becomes a Stonecrop doctype.
+ *
+ * This heuristic excludes:
+ * - Introspection types (`__*`)
+ * - Root operation types (`Query`, `Mutation`, `Subscription`)
+ * - Types with synthetic suffixes (e.g., `*Connection`, `*Edge`, `*Input`)
+ * - Types starting with `Node` interface marker (exact match only)
+ *
+ * @param typeName - The GraphQL type name
+ * @param type - The GraphQL object type definition
+ * @returns `true` if this type should become a Stonecrop doctype
  * @public
  */
-export declare function createNameMapping(sqlNames: string[]): {
-    sqlToFieldname: Map<string, string>;
-    fieldnameToSQL: Map<string, string>;
-    conversions: NameConversion[];
-};
+export declare function defaultIsEntityType(typeName: string, type: GraphQLObjectType): boolean;
 
 /**
  * Doctype metadata - complete definition of a doctype
@@ -489,18 +504,21 @@ export { FieldOptions }
 export { FieldOptions as FieldOptionsType }
 
 /**
- * Field template for TYPE_MAP entries
+ * Field template for TYPE_MAP entries.
+ * Defines the default component and semantic field type for a field.
  * @public
  */
-declare interface FieldTemplate {
+export declare interface FieldTemplate {
+    /**
+     * The Vue component name to render this field (e.g., 'ATextInput', 'ADropdown')
+     */
     component: string;
+    /**
+     * The semantic field type (e.g., 'Data', 'Int', 'Select')
+     */
     fieldtype: StonecropFieldType;
 }
 
-declare interface FieldTemplate_2 extends FieldTemplate {
-    _unmapped?: boolean;
-}
-
 /**
  * Validation configuration for form fields
  * @public
@@ -531,89 +549,146 @@ export declare type FieldValidation = z.infer<typeof FieldValidation>;
 export declare function getDefaultComponent(fieldtype: StonecropFieldType): string;
 
 /**
- * Options for column to field mapping
- * @public
- */
-export declare interface MapColumnOptions {
-    /** Include unmapped type metadata in output */
-    includeUnmappedMeta?: boolean;
-    /** Use camelCase for field names (default: false, keeps snake_case) */
-    useCamelCase?: boolean;
-}
-
-/**
- * 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
+ * Mapping from standard GraphQL scalar types to Stonecrop field types.
+ * These are defined by the GraphQL specification and are always available.
+ *
  * @public
  */
-export declare function mapColumnToField(column: ParsedColumn, _tableRegistry: Map<string, ParsedTable>, options?: MapColumnOptions): ConversionFieldMeta;
+export declare const GQL_SCALAR_MAP: Record<string, FieldTemplate>;
 
 /**
- * Result of name conversion
+ * Extended field metadata with optional GraphQL conversion metadata.
+ * Only present when `includeUnmappedMeta` is enabled.
+ *
  * @public
  */
-export declare interface NameConversion {
-    /** Converted fieldname (camelCase) */
-    fieldname: string;
-    /** Human-readable label */
-    label: string;
-    /** Original SQL name */
-    originalName: string;
+export declare interface GraphQLConversionFieldMeta extends FieldMeta {
+    /** Original GraphQL type name (for debugging/reference) */
+    _graphqlType?: string;
+    /** Marks fields that couldn't be automatically mapped */
+    _unmapped?: boolean;
 }
 
 /**
- * Normalize raw PostgreSQL type string to canonical PostgresType
- * @param rawType - Raw PostgreSQL type string (e.g., 'character varying', 'int4')
+ * Options for converting a GraphQL schema to Stonecrop doctype schemas.
+ * All hooks are optional — sensible defaults are provided for common GraphQL patterns.
+ *
  * @public
  */
-export declare function normalizeType(rawType: string): PostgresType;
+export declare interface GraphQLConversionOptions {
+    /**
+     * GraphQL type names to exclude from conversion.
+     * Applied after `isEntityType` filtering.
+     */
+    exclude?: string[];
+    /**
+     * Whitelist of GraphQL type names to convert.
+     * When provided, only these types are considered (after `isEntityType` filtering).
+     */
+    include?: string[];
+    /**
+     * Per-type, per-field overrides for the converted field definitions.
+     * Outer key is the GraphQL type name, inner key is the field name.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   SalesOrder: {
+     *     totalAmount: { fieldtype: 'Currency', component: 'ACurrencyInput' }
+     *   }
+     * }
+     * ```
+     */
+    typeOverrides?: Record<string, Record<string, Partial<FieldMeta>>>;
+    /**
+     * Map custom or non-standard GraphQL scalar types to Stonecrop field types.
+     * Merged with the built-in scalar maps (GQL_SCALAR_MAP + WELL_KNOWN_SCALARS).
+     * User-provided entries take highest precedence.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   MyCustomMoney: { component: 'ACurrencyInput', fieldtype: 'Currency' },
+     *   PostGISPoint: { component: 'ATextInput', fieldtype: 'Data' }
+     * }
+     * ```
+     */
+    customScalars?: Record<string, Partial<FieldTemplate>>;
+    /**
+     * Custom function to determine if a GraphQL object type represents an entity (→ doctype).
+     * When provided, replaces the default heuristic entirely.
+     *
+     * The default heuristic excludes types matching synthetic patterns:
+     * `*Connection`, `*Edge`, `*Input`, `*Patch`, `*Payload`, `*Condition`,
+     * `*Filter`, `*OrderBy`, `*Aggregate`, `Query`, `Mutation`, `Subscription`, `__*`.
+     *
+     * @param typeName - The GraphQL type name
+     * @param type - The full GraphQL object type definition
+     * @returns `true` if this type should become a Stonecrop doctype
+     */
+    isEntityType?: (typeName: string, type: GraphQLObjectType) => boolean;
+    /**
+     * Custom function to filter which fields on an entity type are included.
+     * When provided, replaces the default field filter.
+     *
+     * The default filter excludes `nodeId`, `__typename`, and `clientMutationId`.
+     *
+     * @param fieldName - The GraphQL field name
+     * @param field - The full GraphQL field definition
+     * @param parentType - The parent entity type
+     * @returns `true` if this field should be included
+     */
+    isEntityField?: (fieldName: string, field: GraphQLField<unknown, unknown>, parentType: GraphQLObjectType) => boolean;
+    /**
+     * Escape hatch: fully override the classification of a specific field.
+     * When this returns a non-null value, it is used as the field definition
+     * (merged with the field name). Return `null` to fall through to default classification.
+     *
+     * @param fieldName - The GraphQL field name
+     * @param field - The full GraphQL field definition
+     * @param parentType - The parent entity type
+     * @returns Partial field meta to use, or `null` for default behavior
+     */
+    classifyField?: (fieldName: string, field: GraphQLField<unknown, unknown>, parentType: GraphQLObjectType) => Partial<FieldMeta> | null;
+    /**
+     * Custom function to derive the database table name from a GraphQL type name.
+     * The default converts PascalCase to snake_case (e.g., `SalesOrder` → `sales_order`).
+     *
+     * Return `undefined` to omit `tableName` from the output.
+     *
+     * @param typeName - The GraphQL type name
+     * @returns The derived table name, or `undefined`
+     */
+    deriveTableName?: (typeName: string) => string | undefined;
+    /**
+     * Include `_graphqlType` and `_unmapped` metadata on converted fields.
+     * Useful for debugging conversions. Defaults to `false`.
+     */
+    includeUnmappedMeta?: boolean;
+}
 
 /**
- * Intermediate representation of a parsed column (from DDL)
+ * Set of scalar type names that are internal to GraphQL servers and should be skipped
+ * during field conversion (they don't represent meaningful data fields).
+ *
  * @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;
-}
+export declare const INTERNAL_SCALARS: Set<string>;
 
 /**
- * Parse PostgreSQL DDL and extract table definitions
- * @param sql - PostgreSQL DDL statements to parse
+ * Input source for the GraphQL schema converter.
+ * Accepts either a standard GraphQL introspection result or an SDL string.
+ *
+ * - `IntrospectionQuery`: The raw result of a GraphQL introspection query (from any server)
+ * - `string`: An SDL (Schema Definition Language) string
+ *
+ * Note: URL fetching is intentionally not supported in the library API.
+ * Use the CLI (`stonecrop-schema generate --endpoint <url>`) for endpoint fetching,
+ * or fetch the introspection result yourself and pass it in.
+ *
  * @public
  */
-export declare function parseDDL(sql: string): ParsedTable[];
+export declare type IntrospectionSource = IntrospectionQuery | string;
 
 /**
  * Parse and validate a doctype, throwing on failure
@@ -624,25 +699,6 @@ export declare function parseDDL(sql: string): ParsedTable[];
  */
 export declare function parseDoctype(data: unknown): DoctypeMeta;
 
-/**
- * Intermediate representation of a parsed table (from DDL)
- * @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) */
-    doctypeName?: string;
-}
-
 /**
  * Parse and validate a field, throwing on failure
  * @param data - Data to parse
@@ -653,22 +709,17 @@ export declare interface ParsedTable {
 export declare function parseField(data: unknown): FieldMeta;
 
 /**
- * Mapping from PostgreSQL types to Stonecrop field types
- * @public
- */
-export declare const PG_TYPE_MAP: Record<PostgresType, FieldTemplate_2>;
-
-/**
- * PostgreSQL types we handle during conversion
- * @public
- */
-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
+ * Convert PascalCase to snake_case (e.g., for deriving table names from type names)
+ * @param pascal - PascalCase string
+ * @returns snake_case string
  * @public
+ * @example
+ * ```typescript
+ * pascalToSnake('SalesOrder') // 'sales_order'
+ * pascalToSnake('SalesOrderItem') // 'sales_order_item'
+ * ```
  */
-export declare type PostgresType = z.infer<typeof PostgresType>;
+export declare function pascalToSnake(pascal: string): string;
 
 /**
  * Converts snake_case to camelCase
@@ -727,12 +778,6 @@ export declare function toPascalCase(tableName: string): string;
  */
 export declare function toSlug(name: string): string;
 
-/**
- * PostgreSQL type aliases to canonical types
- * @public
- */
-export declare const TYPE_ALIASES: Record<string, PostgresType>;
-
 /**
  * Mapping from StonecropFieldType to default Vue component.
  * Components can be overridden in the field definition.
@@ -778,6 +823,18 @@ export declare interface ValidationResult {
     errors: ValidationError[];
 }
 
+/**
+ * Mapping from well-known custom GraphQL scalars to Stonecrop field types.
+ * These cover scalars commonly used across GraphQL servers (PostGraphile, Hasura, etc.)
+ * without baking in knowledge of any specific server.
+ *
+ * Entries here have lower precedence than `customScalars` from options, but higher
+ * precedence than unknown/unmapped scalars.
+ *
+ * @public
+ */
+export declare const WELL_KNOWN_SCALARS: Record<string, FieldTemplate>;
+
 /**
  * Workflow metadata - states and actions for a doctype
  * @public