@stonecrop/schema 0.30.0 → 0.32.0

package/dist/src/converter/aggregate.js

@@ -1,235 +0,0 @@
-/**
- * Aggregate doctype derivation.
- *
- * A table gets two generated doctypes: the entity itself, whose `fields` carry every column and
- * which backs the record form, and an **aggregate** — the collection view over the same table.
- * The aggregate starts with identity alone, because the useful default for a collection is the
- * one column that lets a row be opened, not all forty. Widening it is curation, and curation
- * survives regeneration (see `mergeIntrospectedDoctype`).
- *
- * The two are peers: each is a complete doctype with its own `name` and `slug`, and nothing here
- * encodes a relationship between them. Deriving the aggregate's name from the entity's is a
- * generated encoding, not a readable one — no consumer recovers the pair by parsing a slug.
- *
- * @packageDocumentation
- */
-import pluralize from 'pluralize';
-import { toSlug } from '../naming';
-import { getDoctypeSlug } from '../doctype';
-import { flattenFields, getPrimaryKeyField } from '../field';
-/**
- * The name an entity's aggregate doctype is generated under: the entity's name, pluralised.
- *
- * One definition, because the CLI writes the file under `toSlug` of this and any later caller
- * (a scaffolder, a docs generator) must land on the same name or it silently addresses a
- * different file.
- *
- * `pluralize` rather than appending `s`, because the irregulars are not rare in practice —
- * measured against a consumer's 41 hand-authored aggregate doctypes, this rule reproduces every
- * one of their names, slugs and filenames exactly, while `+ 's'` gets five wrong
- * (`Currencys`, `JournalEntrys`, …).
- *
- * The rule is not total: an already-plural name pluralises to itself. Callers must handle that —
- * see {@link buildAggregateDoctype}.
- *
- * @param doctypeName - the entity doctype's `name`
- * @returns the aggregate doctype's `name`
- * @public
- *
- * @example
- * ```typescript
- * aggregateDoctypeName('SalesOrder') // 'SalesOrders' -> slug 'sales-orders'
- * ```
- */
-export function aggregateDoctypeName(doctypeName) {
-    return pluralize.plural(doctypeName);
-}
-/**
- * Derive the aggregate doctype for a converted entity.
- *
- * Returns `undefined` when no identity column can be found — a natural-key table whose key the
- * converter refuses to guess and whose author has not declared one, or a foreign PostGraphile
- * endpoint that has left the Relay identifier occupying `id` (Stonecrop's own preset moves it to
- * `nodeId`). That is deliberate: an aggregate with an empty `fields` array is a valid doctype that
- * renders a table with no columns, which looks like a data problem rather than a generation one.
- * Emitting nothing and saying so is the loud failure.
- *
- * Identity resolves the same way `getRecordIdField` resolves it — the declared `primaryKey`, then
- * the conventional `id` — so an aggregate is always keyed on the column the client will later ask
- * for. `declaredIdentity` overrides both: SDL cannot express which `UNIQUE` column is the key, so
- * for a natural-key table the answer only exists in the authored file, and the caller that read it
- * passes the fieldname back.
- *
- * @param doctype - a converted entity doctype, as returned by `convertGraphQLSchema`
- * @param declaredIdentity - fieldname the authored doctype declares as its `primaryKey`, when the
- *   caller has read one. Must name a field the converter emitted; the caller checks that, because
- *   only it can say whether a missing one is a dropped column or a typo.
- * @returns the aggregate doctype, or `undefined` when no identity column exists
- * @public
- *
- * @example
- * ```typescript
- * const [order] = convertGraphQLSchema(sdl, { include: ['Order'] })
- * const aggregate = buildAggregateDoctype(order)
- * // { name: 'Orders', slug: 'orders', fields: [ the id field ] }
- * ```
- */
-export function buildAggregateDoctype(doctype, declaredIdentity) {
-    const identity = findIdentityField(doctype.fields, declaredIdentity);
-    if (!identity)
-        return undefined;
-    const name = aggregateDoctypeName(doctype.name);
-    // An already-plural name pluralises to itself, which would give the aggregate the entity's own
-    // `name` *and* its filename. Both write paths are silent about it: the CLI writes the file twice
-    // in one run, and the middleware's registry is a Map keyed by name, so the later read wins in
-    // whatever order `readdirSync` returns. Refusing is the only loud option.
-    if (name === doctype.name)
-        return undefined;
-    // `primaryKey` is stamped rather than copied through: a declared identity is not marked on the
-    // converter's own field, and an aggregate whose one column carries no marker resolves identity
-    // through `getRecordIdField`'s `id` fallback — a column it does not have, so every listed row is
-    // silently dropped. Rebuilt with `source` last so the key order matches an entity's identity
-    // field and both files stay byte-stable.
-    //
-    // A copy, not a reference: the two doctypes are written to separate files and an edit to one
-    // must not reach the other.
-    const { source, ...rest } = identity;
-    return {
-        name,
-        slug: toSlug(name),
-        fields: [{ ...rest, primaryKey: true, ...(source === undefined ? {} : { source }) }],
-    };
-}
-/**
- * The field an aggregate is keyed on: an identity the author declared, else the primary key the
- * converter derived, else the conventional `id`.
- *
- * The author wins because the authored doctype is the source of truth — generation verifies it and
- * never overwrites it (see `mergeIntrospectedDoctype`), and the divergence is already reported as
- * identity drift.
- *
- * Calls `getPrimaryKeyField` for the derived half rather than restating it: a restatement drifted
- * exactly as one does, staying top-level while the helper learned to descend into fieldsets.
- *
- * @internal
- */
-function findIdentityField(fields, declared) {
-    if (declared !== undefined)
-        return fields.find(field => field.fieldname === declared);
-    return getPrimaryKeyField(fields) ?? fields.find(field => field.fieldname === 'id');
-}
-/**
- * The doctypes in a run that get a URL of their own.
- *
- * A child table has no page: its rows exist inside a parent and are edited there, so a route for
- * it is an address nothing can link to. The declaration that says so is the parent's `links` entry
- * with a to-many cardinality — which the server derives from the foreign keys it treats as owning,
- * so this reads what the schema states rather than guessing from a name.
- *
- * The rule is *listed by something, referenced by nothing*. A single reference wins over any number
- * of listings, and the asymmetry is deliberate: a doctype that is both a parent's rows and another
- * doctype's link target — a recipe task, say, embedded in its recipe and pointed at by four other
- * records — needs somewhere for those links to navigate to. Denying it leaves the arrow on an
- * `AFormLink` dead, which fails silently; granting it leaves a URL nobody visits, which does not.
- *
- * Scoped to one run, so a partial generation sees a partial graph and grants more routes than a
- * whole one would. That is the safe direction, and the extra routes are deletable — an authored
- * file's keys survive regeneration untouched.
- *
- * @internal
- */
-function routableDoctypes(entities) {
-    const listed = new Set();
-    const referenced = new Set();
-    for (const entity of entities) {
-        for (const link of Object.values(entity.links ?? {})) {
-            if (link.cardinality === 'noneOrMany' || link.cardinality === 'atLeastOne')
-                listed.add(link.target);
-            else
-                referenced.add(link.target);
-        }
-        // `flattenFields` rather than a top-level scan: a link inside a fieldset is still a reference,
-        // and the two ways to answer this question have already drifted apart once.
-        for (const field of flattenFields(entity.fields)) {
-            if ('doctype' in field && typeof field.doctype === 'string')
-                referenced.add(field.doctype);
-        }
-    }
-    return new Set(entities
-        .filter(entity => {
-        const slug = getDoctypeSlug(entity);
-        return referenced.has(slug) || !listed.has(slug);
-    })
-        .map(entity => entity.name));
-}
-/**
- * Expand converted entities into the set of doctype files to write.
- *
- * Each table yields two: the entity, whose fields carry every column and which backs the record
- * form, and its aggregate — the collection view. They are written as peers, one file each, with
- * no key relating them.
- *
- * Separate from the CLI because the pairing of a file to its verification basis is the part that
- * is easy to get wrong and impossible to notice: getting it wrong does not throw, it just reports
- * drift that is not there, forever.
- *
- * @param entities - `convertGraphQLSchema` output
- * @param options - see {@link GenerationPlanOptions}
- * @returns one entry per file to write
- * @public
- */
-export function planGeneration(entities, options = {}) {
-    const entityNames = new Set(entities.map(entity => entity.name));
-    const claimed = new Set();
-    const routable = routableDoctypes(entities);
-    return entities.flatMap(entity => {
-        // Written out in full rather than as a segment the host assembles: the record parameter has
-        // to live somewhere, and a host given `/order` cannot know whether this doctype is the
-        // collection or the record without asking a second question. The pair shares the entity's
-        // slug, so no URL ever carries a plural.
-        const segment = `/${getDoctypeSlug(entity)}`;
-        const routed = routable.has(entity.name) ? { ...entity, route: `${segment}/:id` } : entity;
-        // `basis` is the same object as `generated` for an entity — it is verified against itself.
-        const self = { generated: routed, basis: routed, subset: false };
-        if (options.noAggregates)
-            return [self];
-        // Name collisions are checked here rather than in the builder because only this function
-        // holds the whole set. Reported before the identity check so each refusal names its own
-        // cause — the two are repaired differently.
-        const name = aggregateDoctypeName(entity.name);
-        if (name === entity.name) {
-            options.onWarning?.(`${entity.name} is already plural, so its aggregate would take the same name and the same ` +
-                `file. No aggregate was generated. Rename the doctype to its singular form, or author ` +
-                `${entity.slug}.json's collection view by hand.`);
-            return [self];
-        }
-        if (entityNames.has(name) || claimed.has(name)) {
-            options.onWarning?.(`${entity.name}'s aggregate would be named ${name}, which is already taken by another ` +
-                `doctype in this run. No aggregate was generated — one of the two needs an explicit ` +
-                `name via the doctypeNames option.`);
-            return [self];
-        }
-        // Checked here rather than in the builder because only the caller knows whether a name that
-        // matches nothing is a dropped column or a typo — and an aggregate built around a field the
-        // table has no column for renders a collection whose only column is absent from every row.
-        const declared = options.identity?.[entity.name];
-        if (declared !== undefined && !entity.fields.some(field => field.fieldname === declared)) {
-            options.onWarning?.(`${entity.name} declares its primaryKey on '${declared}', which the schema has no column for. ` +
-                `No aggregate was generated — correct the declaration in ${entity.slug}.json, or restore the ` +
-                `column to the table.`);
-            return [self];
-        }
-        const aggregate = buildAggregateDoctype(entity, declared);
-        if (!aggregate) {
-            options.onWarning?.(`${entity.name} has no derivable identity column, so no aggregate doctype was generated. ` +
-                `Declare a primaryKey on ${entity.slug}.json and re-run.`);
-            return [self];
-        }
-        claimed.add(name);
-        // The basis is the entity itself: an aggregate is verified against the table it curates from,
-        // not against its own one-field generation. Drift lines take their name from the authored file
-        // being checked, so they already name the file the reader has to edit.
-        const listed = routable.has(entity.name) ? { ...aggregate, route: segment } : aggregate;
-        return [self, { generated: listed, basis: entity, subset: true }];
-    });
-}

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

@@ -1,43 +0,0 @@
-/**
- * Reading an authored doctype — the JSON as it sits on disk, before any parsing.
- *
- * A separate reader from `@stonecrop/schema`'s `flattenFields`/`getPrimaryKeyField` because the two
- * operate on different *shapes*, not different rules: those take parsed `DoctypeField`s and branch
- * on the `kind` discriminant the Zod parser synthesizes, which authored JSON does not carry.
- * `getPrimaryKeyField` on a raw file therefore returns `undefined` — indistinguishable from "no key
- * declared", which is the exact condition its callers are testing.
- *
- * Every question about authored JSON is answered here once, so the rule cannot drift between the
- * merge and the generation plan.
- *
- * @internal
- */
-/**
- * A doctype as it exists on disk: a plain object that may carry keys this package does not model
- * (`handler` on an action, `filterFunction` on a field, whatever an app has added). Typing it
- * loosely is what lets the merge round-trip those keys untouched instead of dropping them.
- *
- * @public
- */
-export type AuthoredDoctype = Record<string, unknown>;
-/** @internal */
-export declare function isAuthoredRecord(value: unknown): value is AuthoredDoctype;
-/**
- * Flatten authored fields, descending into fieldsets.
- *
- * A fieldset is a layout grouping, not a scope: a field inside one is still a field of the doctype,
- * with a column of its own and a key it may declare.
- *
- * @internal
- */
-export declare function flattenAuthored(fields: readonly AuthoredDoctype[]): AuthoredDoctype[];
-/**
- * The fieldname an authored doctype declares as its identity, or `undefined` when it declares none.
- *
- * Descends into fieldsets, because a nested `primaryKey` is a real declaration — ignoring one is
- * what `getPrimaryKeyField` was fixed for.
- *
- * @internal
- */
-export declare function authoredPrimaryKey(doctype: AuthoredDoctype): string | undefined;
-//# sourceMappingURL=authored.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"authored.d.ts","sourceRoot":"","sources":["../../../src/converter/authored.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAErD,gBAAgB;AAChB,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAEzE;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,GAAG,eAAe,EAAE,CAUrF;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAI/E"}

package/dist/src/converter/authored.js

@@ -1,52 +0,0 @@
-/**
- * Reading an authored doctype — the JSON as it sits on disk, before any parsing.
- *
- * A separate reader from `@stonecrop/schema`'s `flattenFields`/`getPrimaryKeyField` because the two
- * operate on different *shapes*, not different rules: those take parsed `DoctypeField`s and branch
- * on the `kind` discriminant the Zod parser synthesizes, which authored JSON does not carry.
- * `getPrimaryKeyField` on a raw file therefore returns `undefined` — indistinguishable from "no key
- * declared", which is the exact condition its callers are testing.
- *
- * Every question about authored JSON is answered here once, so the rule cannot drift between the
- * merge and the generation plan.
- *
- * @internal
- */
-/** @internal */
-export function isAuthoredRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-/**
- * Flatten authored fields, descending into fieldsets.
- *
- * A fieldset is a layout grouping, not a scope: a field inside one is still a field of the doctype,
- * with a column of its own and a key it may declare.
- *
- * @internal
- */
-export function flattenAuthored(fields) {
-    const out = [];
-    for (const field of fields) {
-        if (Array.isArray(field.schema)) {
-            out.push(...flattenAuthored(field.schema.filter(isAuthoredRecord)));
-        }
-        else {
-            out.push(field);
-        }
-    }
-    return out;
-}
-/**
- * The fieldname an authored doctype declares as its identity, or `undefined` when it declares none.
- *
- * Descends into fieldsets, because a nested `primaryKey` is a real declaration — ignoring one is
- * what `getPrimaryKeyField` was fixed for.
- *
- * @internal
- */
-export function authoredPrimaryKey(doctype) {
-    if (!Array.isArray(doctype.fields))
-        return undefined;
-    const declared = flattenAuthored(doctype.fields.filter(isAuthoredRecord)).find(f => f.primaryKey === true);
-    return typeof declared?.fieldname === 'string' ? declared.fieldname : undefined;
-}

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

@@ -1,60 +0,0 @@
-/**
- * Default heuristics for identifying entity types and fields in a GraphQL schema.
- *
- * These heuristics work across common GraphQL servers (PostGraphile, Hasura, Apollo, etc.)
- * by detecting widely-adopted conventions like the Relay connection pattern.
- *
- * All heuristics can be overridden via the `isEntityType`, `isEntityField`, and
- * `classifyField` options in `GraphQLConversionOptions`.
- *
- * @packageDocumentation
- */
-import { type GraphQLObjectType, type GraphQLField } from 'graphql';
-import type { GraphQLConversionFieldMeta, GraphQLConversionOptions } from './types';
-/**
- * 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 defaultIsEntityType(typeName: string, type: GraphQLObjectType): boolean;
-/**
- * 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, whose interfaces declare its Relay identifier
- * @returns `true` if this field should be included
- * @public
- */
-export declare function defaultIsEntityField(fieldName: string, _field: GraphQLField<unknown, unknown>, parentType: GraphQLObjectType): boolean;
-/**
- * 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 function classifyFieldType(fieldName: string, field: GraphQLField<unknown, unknown>, entityTypes: Set<string>, options?: GraphQLConversionOptions): GraphQLConversionFieldMeta;
-//# sourceMappingURL=heuristics.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"heuristics.d.ts","sourceRoot":"","sources":["../../../src/converter/heuristics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAON,KAAK,iBAAiB,EACtB,KAAK,YAAY,EAGjB,MAAM,SAAS,CAAA;AAGhB,OAAO,KAAK,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAA;AA+BnF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CA8BtF;AA+CD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CACnC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,EACtC,UAAU,EAAE,iBAAiB,GAC3B,OAAO,CAGT;AAyED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAChC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,EACrC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EACxB,OAAO,GAAE,wBAA6B,GACpC,0BAA0B,CAkG5B"}