@stonecrop/schema 0.31.0 → 0.32.0

package/dist/src/converter/merge.js

@@ -1,136 +0,0 @@
-/**
- * Merge introspected schema facts into an already-authored doctype.
- *
- * The authored doctype is the source of truth. Generation **verifies** it and stamps provenance;
- * it does not overwrite. That polarity is deliberate and load-bearing — a doctype legitimately
- * declares a `primaryKey` the schema cannot express. A natural business key is very often a
- * `UNIQUE` constraint rather than the table's `PRIMARY KEY`, and where a table carries several
- * uniques no rule can pick between them. Overwriting identity from the schema would silently
- * re-key such a doctype on every regeneration and break the handlers that key on the old value.
- *
- * So divergence is **reported, never applied** — a human decides. The only mutation this performs
- * is adding `source: 'introspected'` to fields confirmed to exist in the GraphQL schema.
- *
- * @packageDocumentation
- */
-import { INTROSPECTED_IDENTITY_PROPS } from '../field';
-import { authoredPrimaryKey, flattenAuthored, isAuthoredRecord } from './authored';
-function describe(value) {
-    return value === undefined ? '—' : JSON.stringify(value);
-}
-/**
- * Verify an authored doctype against freshly generated output and stamp provenance.
- *
- * @param authored - the doctype as it exists on disk; every key not named below is preserved verbatim
- * @param generated - `convertGraphQLSchema` output for the corresponding GraphQL type. For a
- *   `subset` merge this is the **entity**, whose fields are the set the subset is curated from
- * @param options - see {@link MergeOptions}
- * @returns the doctype to write, plus a drift report
- *
- * @example
- * ```ts
- * const [generated] = convertGraphQLSchema(introspection, { include: ['Uom'] })
- * const { doctype, drift } = mergeIntrospectedDoctype(JSON.parse(onDisk), generated)
- * if (drift.identityDrift.length) console.warn(drift.identityDrift.join('\n'))
- * ```
- *
- * @public
- */
-export function mergeIntrospectedDoctype(authored, generated, options = {}) {
-    const authoredFields = Array.isArray(authored.fields) ? authored.fields.filter(isAuthoredRecord) : [];
-    const generatedByName = new Map(generated.fields.map(f => [f.fieldname, f]));
-    // Expanding links live in `links`, not `fields`, so a field naming one is modelled, not orphaned.
-    const generatedLinkNames = new Set(Object.keys(generated.links ?? {}));
-    const drift = {
-        doctype: typeof authored.name === 'string' ? authored.name : '(unnamed)',
-        mode: 'clean',
-        tagged: [],
-        orphan: [],
-        omitted: [],
-        componentDrift: [],
-        requiredDrift: [],
-        identityDrift: [],
-    };
-    const tag = (field) => {
-        // Containers have no column of their own; recurse and leave the container itself alone.
-        if (Array.isArray(field.schema)) {
-            return { ...field, schema: field.schema.filter(isAuthoredRecord).map(tag) };
-        }
-        const name = typeof field.fieldname === 'string' ? field.fieldname : '';
-        const match = generatedByName.get(name);
-        if (!match) {
-            // A computed field declares up front that it has no backing column, so it is not a
-            // discrepancy. Everything else is worth surfacing — it may be an app component, or a
-            // column that has since been dropped.
-            if (field.computed !== true && !generatedLinkNames.has(name))
-                drift.orphan.push(name);
-            return field;
-        }
-        drift.tagged.push(name);
-        if (match.component !== field.component) {
-            drift.componentDrift.push(`${name}: authored=${describe(field.component)} schema=${describe(match.component)}`);
-        }
-        if (Boolean(match.required) !== Boolean(field.required)) {
-            drift.requiredDrift.push(`${name}: authored=${Boolean(field.required)} schema=${Boolean(match.required)}`);
-        }
-        for (const prop of INTROSPECTED_IDENTITY_PROPS) {
-            if (prop === 'fieldname' || prop === 'required')
-                continue;
-            const authoredValue = field[prop];
-            const schemaValue = match[prop];
-            // Absent on both sides is agreement, not drift — most fields set none of these.
-            if (authoredValue === undefined && schemaValue === undefined)
-                continue;
-            if (JSON.stringify(authoredValue) !== JSON.stringify(schemaValue)) {
-                drift.identityDrift.push(`${name}.${prop}: authored=${describe(authoredValue)} schema=${describe(schemaValue)}`);
-            }
-        }
-        return { ...field, source: 'introspected' };
-    };
-    const merged = { ...authored, fields: authoredFields.map(tag) };
-    // A curated subset omits columns by definition, so the bucket that reports omissions has
-    // nothing true to say about one.
-    if (!options.subset) {
-        const authoredNames = new Set(flattenAuthored(authoredFields).map(f => f.fieldname));
-        drift.omitted = generated.fields.map(f => f.fieldname).filter(n => !authoredNames.has(n));
-    }
-    // Classify identity last, once every field has been compared.
-    const authoredPk = authoredPrimaryKey(authored);
-    const generatedPk = generated.fields.find(f => f.primaryKey === true);
-    if (authoredPk && generatedPk && authoredPk !== generatedPk.fieldname) {
-        drift.mode = 'partial';
-        drift.reason = `authored primary key '${authoredPk}' is not the derivable '${generatedPk.fieldname}' — left as authored`;
-    }
-    else if (authoredPk && !generatedPk) {
-        drift.mode = 'partial';
-        drift.reason = `authored primary key '${authoredPk}' is not derivable from the schema — left as authored`;
-    }
-    else if (!authoredPk && generatedPk) {
-        drift.mode = 'partial';
-        drift.reason = `schema suggests '${generatedPk.fieldname}' as primary key but the doctype declares none — not applied`;
-    }
-    return { doctype: merged, drift };
-}
-/**
- * Render a drift report as human-readable lines. Empty when generation agrees with the doctype.
- *
- * @param drift - a report from {@link mergeIntrospectedDoctype}
- * @returns one line per finding, ready to print
- *
- * @public
- */
-export function formatDoctypeDrift(drift) {
-    const lines = [];
-    if (drift.reason)
-        lines.push(`  ${drift.doctype}: ${drift.reason}`);
-    const bucket = (label, entries) => {
-        if (entries.length)
-            lines.push(`  ${drift.doctype}: ${label} ${entries.join('; ')}`);
-    };
-    bucket('identity drift', drift.identityDrift);
-    bucket('component drift', drift.componentDrift);
-    bucket('required drift', drift.requiredDrift);
-    bucket('authored fields with no schema field:', drift.orphan);
-    bucket('schema fields not modelled:', drift.omitted);
-    return lines;
-}

package/dist/src/converter/scalars.d.ts

@@ -1,46 +0,0 @@
-/**
- * GraphQL Scalar Type Mappings
- *
- * Maps standard GraphQL scalars and well-known custom scalars to Stonecrop field types.
- * Source-agnostic — covers scalars commonly emitted by PostGraphile, Hasura, Apollo, etc.
- *
- * Users can extend these via the `customScalars` option in `GraphQLConversionOptions`.
- *
- * @packageDocumentation
- */
-import type { FieldTemplate } from './types';
-/**
- * Mapping from standard GraphQL scalar types to Stonecrop field types.
- * These are defined by the GraphQL specification and are always available.
- *
- * @public
- */
-export declare const GQL_SCALAR_MAP: Record<string, FieldTemplate>;
-/**
- * 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>;
-/**
- * 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 const INTERNAL_SCALARS: Set<string>;
-/**
- * Build a merged scalar map from the built-in maps and user-provided custom scalars.
- * Precedence (highest to lowest): customScalars → GQL_SCALAR_MAP → WELL_KNOWN_SCALARS
- *
- * @param customScalars - User-provided scalar overrides
- * @returns Merged scalar map
- * @public
- */
-export declare function buildScalarMap(customScalars?: Record<string, Partial<FieldTemplate>>): Record<string, FieldTemplate>;
-//# sourceMappingURL=scalars.d.ts.map

package/dist/src/converter/scalars.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"scalars.d.ts","sourceRoot":"","sources":["../../../src/converter/scalars.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAMxD,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAuB5D,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,aAAsB,CAAA;AAEnD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAgBpH"}

package/dist/src/converter/scalars.js

@@ -1,83 +0,0 @@
-/**
- * GraphQL Scalar Type Mappings
- *
- * Maps standard GraphQL scalars and well-known custom scalars to Stonecrop field types.
- * Source-agnostic — covers scalars commonly emitted by PostGraphile, Hasura, Apollo, etc.
- *
- * Users can extend these via the `customScalars` option in `GraphQLConversionOptions`.
- *
- * @packageDocumentation
- */
-/**
- * Mapping from standard GraphQL scalar types to Stonecrop field types.
- * These are defined by the GraphQL specification and are always available.
- *
- * @public
- */
-export const GQL_SCALAR_MAP = {
-    String: { component: 'ATextInput' },
-    Int: { component: 'ANumericInput' },
-    Float: { component: 'ANumericInput' },
-    Boolean: { component: 'ACheckbox' },
-    ID: { component: 'ATextInput' },
-};
-/**
- * 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 const WELL_KNOWN_SCALARS = {
-    // Arbitrary precision / large numbers — all numeric variants render with ANumericInput.
-    BigFloat: { component: 'ANumericInput' },
-    BigDecimal: { component: 'ANumericInput' },
-    Decimal: { component: 'ANumericInput' },
-    BigInt: { component: 'ANumericInput' },
-    Long: { component: 'ANumericInput' },
-    // Identifiers
-    UUID: { component: 'ATextInput' },
-    // Date / Time — no dedicated Time SFC exists; Time falls back to a plain text input.
-    DateTime: { component: 'ADateTime' },
-    Datetime: { component: 'ADateTime' },
-    Date: { component: 'ADate' },
-    Time: { component: 'ATextInput' },
-    Interval: { component: 'ADuration' },
-    Duration: { component: 'ADuration' },
-    // Structured data
-    JSON: { component: 'ACodeEditor' },
-    JSONObject: { component: 'ACodeEditor' },
-    JsonNode: { component: 'ACodeEditor' },
-};
-/**
- * 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 const INTERNAL_SCALARS = new Set(['Cursor']);
-/**
- * Build a merged scalar map from the built-in maps and user-provided custom scalars.
- * Precedence (highest to lowest): customScalars → GQL_SCALAR_MAP → WELL_KNOWN_SCALARS
- *
- * @param customScalars - User-provided scalar overrides
- * @returns Merged scalar map
- * @public
- */
-export function buildScalarMap(customScalars) {
-    const merged = { ...WELL_KNOWN_SCALARS };
-    // Standard scalars override well-known
-    for (const [key, value] of Object.entries(GQL_SCALAR_MAP)) {
-        merged[key] = value;
-    }
-    // Custom scalars override everything
-    if (customScalars) {
-        for (const [key, value] of Object.entries(customScalars)) {
-            merged[key] = { component: value.component ?? 'ATextInput' };
-        }
-    }
-    return merged;
-}

package/dist/src/converter/types.d.ts

@@ -1,157 +0,0 @@
-/**
- * Types for the GraphQL introspection to Stonecrop schema converter.
- * Source-agnostic — works with any GraphQL server (PostGraphile, Hasura, Apollo, etc.)
- * @packageDocumentation
- */
-import type { IntrospectionQuery } from 'graphql';
-import type { GraphQLObjectType, GraphQLField } from 'graphql';
-import type { ValueField } from '../field';
-/**
- * The component a GraphQL scalar maps to.
- *
- * A one-property interface rather than a bare string so `customScalars` stays extensible: an
- * override is a `Partial<FieldTemplate>`, and widening this later does not change that signature.
- *
- * @public
- */
-export interface FieldTemplate {
-    /** The Vue component name to render fields of this scalar type (e.g. `'ATextInput'`). */
-    component: string;
-}
-/**
- * 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 type IntrospectionSource = IntrospectionQuery | string;
-/**
- * Options for converting a GraphQL schema to Stonecrop doctype schemas.
- * All hooks are optional — sensible defaults are provided for common GraphQL patterns.
- *
- * @public
- */
-export 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[];
-    /**
-     * Emit a doctype under a different name than its GraphQL type. Key is the GraphQL type name,
-     * value is the doctype `name`; `slug` is derived from the value.
-     *
-     * This exists for the case where a doctype is not one-to-one with a table — a second view over
-     * an existing type, say, distinguished only by presentation. Without it the converter can only
-     * ever name a doctype after its type.
-     *
-     * Keep it consistent with the middleware's `tables` option, which maps the resulting doctype
-     * name to its SQL target.
-     *
-     * @example
-     * ```typescript
-     * { Plan: 'Planner' }   // emits a doctype named Planner, slug 'planner', from type Plan
-     * ```
-     */
-    doctypeNames?: Record<string, string>;
-    /**
-     * Called with any advisory message raised during conversion — currently only the
-     * un-normalized-PostGraphile warning. Left to the caller so the library never writes to the
-     * console itself.
-     */
-    onWarning?: (message: string) => void;
-    /**
-     * Map custom or non-standard GraphQL scalar types to the component that renders them.
-     * Merged with the built-in scalar maps (GQL_SCALAR_MAP + WELL_KNOWN_SCALARS).
-     * User-provided entries take highest precedence.
-     *
-     * @example
-     * ```typescript
-     * {
-     *   MyCustomMoney: { component: 'ANumericInput' },
-     *   PostGISPoint: { component: 'ATextInput' }
-     * }
-     * ```
-     */
-    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) => Omit<Partial<ValueField>, 'kind'> | null;
-    /**
-     * Include `_graphqlType` and `_unmapped` metadata on converted fields.
-     * Useful for debugging conversions. Defaults to `false`.
-     */
-    includeUnmappedMeta?: boolean;
-}
-/**
- * Extended field metadata with optional GraphQL conversion metadata.
- * Only present when `includeUnmappedMeta` is enabled.
- *
- * @public
- */
-export interface GraphQLConversionFieldMeta extends ValueField {
-    /** Original GraphQL type name (for debugging/reference) */
-    _graphqlType?: string;
-    /** Marks fields that couldn't be automatically mapped */
-    _unmapped?: boolean;
-    /** Marks relationship fields that belong in `links`, not `fields` */
-    _isLink?: boolean;
-}
-/**
- * Output of GraphQL schema conversion — one per entity type.
- *
- * @public
- */
-export interface ConvertedGraphQLDoctype extends Omit<DoctypeMeta, 'fields'> {
-    /** Field definitions — GraphQL conversion metadata stripped; same shape as DoctypeMeta.fields */
-    fields: ValueField[];
-    /** Original GraphQL type name (for debugging/reference) */
-    _graphqlTypeName?: string;
-}
-import type { DoctypeMeta } from '../doctype';
-//# sourceMappingURL=types.d.ts.map

package/dist/src/converter/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/converter/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AACjD,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAE1C;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC7B,yFAAyF;IACzF,SAAS,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,mBAAmB,GAAG,kBAAkB,GAAG,MAAM,CAAA;AAE7D;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACxC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAElB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAElB;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAErC;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IAErC;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC,CAAA;IAEtD;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,KAAK,OAAO,CAAA;IAErE;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,UAAU,EAAE,iBAAiB,KAAK,OAAO,CAAA;IAEpH;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,CACf,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,EACrC,UAAU,EAAE,iBAAiB,KACzB,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;IAE7C;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA2B,SAAQ,UAAU;IAC7D,2DAA2D;IAC3D,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,yDAAyD;IACzD,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,qEAAqE;IACrE,OAAO,CAAC,EAAE,OAAO,CAAA;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAwB,SAAQ,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC;IAC3E,iGAAiG;IACjG,MAAM,EAAE,UAAU,EAAE,CAAA;IACpB,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,MAAM,CAAA;CACzB;AAGD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA"}

package/dist/src/converter/types.js

@@ -1,5 +0,0 @@
-/**
- * Types for the GraphQL introspection to Stonecrop schema converter.
- * Source-agnostic — works with any GraphQL server (PostGraphile, Hasura, Apollo, etc.)
- * @packageDocumentation
- */