@builder-builder/builder 0.0.13 → 0.0.14

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import { writeFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { generateOrderType } from './codegen/index.js';
+const DEFAULT_API_URL = 'https://builder-builder.com';
+run().catch((caught) => {
+    const message = caught instanceof Error ? caught.message : String(caught);
+    process.stderr.write(`bb: ${message}\n`);
+    process.exit(1);
+});
+async function run() {
+    const { values } = parseArgs({
+        options: {
+            id: { type: 'string' },
+            out: { type: 'string' },
+            api: { type: 'string', default: DEFAULT_API_URL },
+            key: { type: 'string' }
+        },
+        strict: true
+    });
+    const id = values.id;
+    const out = values.out;
+    if (id == null || out == null) {
+        process.stderr.write('Usage: bb --id <entity-id> --out <file> [--api <url>] [--key <api-key>]\n');
+        process.exit(1);
+        return;
+    }
+    const apiUrl = values.api ?? DEFAULT_API_URL;
+    const apiKey = values.key ?? process.env.BB_API_KEY;
+    if (apiKey == null || apiKey.length === 0) {
+        throw new Error('missing API key — pass --key or set BB_API_KEY');
+    }
+    const entity = await fetchEntity({ apiUrl, id, apiKey });
+    const generated = generateOrderType({ name: entity.name, builder: entity.builder });
+    const fetchedAt = new Date().toISOString();
+    const header = `// AUTO-GENERATED — DO NOT EDIT\n` +
+        `// Source: ${id} (${entity.name}) — fetched ${fetchedAt}\n` +
+        `// Regenerate: bb --id ${id} --out ${out}\n\n`;
+    writeFileSync(out, header + generated);
+    process.stdout.write(`bb: wrote ${out}\n`);
+}
+async function fetchEntity(options) {
+    const url = `${options.apiUrl.replace(/\/$/, '')}/api/builder/${options.id}`;
+    const response = await fetch(url, {
+        headers: { 'X-Builder-Builder-Key': options.apiKey }
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`fetch ${url} failed: ${response.status} ${response.statusText} — ${body}`);
+    }
+    const payload = (await response.json());
+    return payload;
+}

package/dist/codegen/index.d.ts

@@ -0,0 +1,7 @@
+import type { BuilderRefEntities, BuilderSerialised } from '../entities/index.js';
+export type GenerateOrderTypeInput = {
+    readonly name: string;
+    readonly builder: BuilderSerialised;
+    readonly references?: BuilderRefEntities;
+};
+export declare function generateOrderType(input: GenerateOrderTypeInput): string;

package/dist/codegen/index.js

@@ -0,0 +1,212 @@
+import ts from 'typescript';
+import * as v from 'valibot';
+import { check } from '../check.js';
+import { BuilderException } from '../exception.js';
+import { optionGraph, variantsFor } from '../mappers/index.js';
+import { validateBuilder } from '../validate/index.js';
+import { tsmember, tstype } from './template.js';
+export function generateOrderType(input) {
+    const [validated, errors] = validateBuilder(input.builder, input.references ?? []);
+    if (errors.length > 0) {
+        throw new BuilderException(errors);
+    }
+    const typeName = `${pascalCase(input.name)}Order`;
+    const typeNode = renderModelOrder(validated.model);
+    const declaration = ts.factory.createTypeAliasDeclaration([ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)], typeName, undefined, typeNode);
+    const sourceFile = ts.createSourceFile('generated.ts', '', ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
+    const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });
+    return `${printer.printNode(ts.EmitHint.Unspecified, declaration, sourceFile)}\n`;
+}
+function renderModelOrder(model) {
+    const graph = optionGraph(model);
+    const componentMembers = model.components.map((component) => {
+        return renderComponentMember(component, model, graph);
+    });
+    const collectionMembers = model.collections.map((collection) => {
+        return renderCollectionMember(collection);
+    });
+    return ts.factory.createTypeLiteralNode([...componentMembers, ...collectionMembers]);
+}
+function renderComponentMember(component, model, graph) {
+    const variant = renderComponentVariant(component, model, graph);
+    return tsmember('readonly <%= name %>: <%= variant %> | null;', {
+        name: propertyName(component.name),
+        variant
+    });
+}
+function renderComponentVariant(component, model, graph) {
+    const instance = renderComponentInstance(component, model, graph);
+    const detailFields = extractDetailFields(component.payload);
+    if (detailFields.length === 0) {
+        return tstype('{ readonly instance: <%= i %> }', { i: instance });
+    }
+    const details = renderDetailFields(detailFields);
+    return tstype('{ readonly instance: <%= i %>; readonly details: <%= d %> }', {
+        i: instance,
+        d: details
+    });
+}
+function renderComponentInstance(component, model, graph) {
+    rejectUnsupportedDependencyPaths(component);
+    const observedValues = perKeyValueSets(variantsFor(component, graph));
+    const members = [];
+    observedValues.forEach((values, key) => {
+        members.push(tsmember('readonly <%= name %>: <%= type %>;', {
+            name: propertyName(key),
+            type: renderOptionValueType(key, values, model)
+        }));
+    });
+    return ts.factory.createTypeLiteralNode(members);
+}
+function rejectUnsupportedDependencyPaths(component) {
+    const paths = component.paths ?? [];
+    paths.forEach((path) => {
+        if (path.length !== 1) {
+            throw new Error(`codegen: multi-segment dependency paths are not yet supported (component '${component.name}', path ${JSON.stringify(path)})`);
+        }
+        const [head] = path;
+        check.assert(v.string(), head, `codegen invariant: component dependency path head must be a string (component '${component.name}', path ${JSON.stringify(path)})! ❌`);
+    });
+}
+function perKeyValueSets(variants) {
+    const result = new Map();
+    variants.forEach((instance) => {
+        Object.entries(instance).forEach(([key, value]) => {
+            const existing = result.get(key) ?? new Set();
+            existing.add(value);
+            result.set(key, existing);
+        });
+    });
+    return result;
+}
+function renderOptionValueType(name, observedValues, model) {
+    const option = model.options.find((candidate) => candidate.name === name);
+    check.truthy(option, `codegen invariant: option '${name}' referenced by a component must be defined in the model! ❌`);
+    return renderOptionValueShape(option.payload, observedValues);
+}
+function renderOptionValueShape(payload, observedValues) {
+    if (payload.type === 'toggle') {
+        return maybeNullable(primitiveTypeNode(payload.valueType), payload.isOptional);
+    }
+    if (payload.type === 'select') {
+        const literals = Array.from(observedValues)
+            .filter((value) => typeof value === 'string')
+            .map((value) => {
+            return ts.factory.createLiteralTypeNode(ts.factory.createStringLiteral(value));
+        });
+        return maybeNullable(unionOf(literals), payload.isOptional);
+    }
+    if (payload.type === 'enable' || payload.type === 'unless') {
+        return renderOptionValueShape(payload.payload, observedValues);
+    }
+    const branches = Object.values(payload.selectMap).filter((branch) => branch != null);
+    const [first] = branches;
+    if (first == null) {
+        return ts.factory.createKeywordTypeNode(ts.SyntaxKind.NeverKeyword);
+    }
+    return renderOptionValueShape(first, observedValues);
+}
+function extractDetailFields(payload) {
+    if (!('type' in payload)) {
+        return payload.fields;
+    }
+    if (payload.type === 'enable' || payload.type === 'unless') {
+        return extractDetailFields(payload.payload);
+    }
+    const branches = Object.values(payload.selectMap).filter((branch) => branch != null);
+    const [first] = branches;
+    if (first == null) {
+        return [];
+    }
+    return extractDetailFields(first);
+}
+function renderDetailFields(fields) {
+    const members = fields.map((field) => {
+        return tsmember('readonly <%= name %>: <%= type %>;', {
+            name: propertyName(field.name),
+            type: maybeNullable(primitiveTypeNode(field.valueType), field.isOptional)
+        });
+    });
+    return ts.factory.createTypeLiteralNode(members);
+}
+function renderCollectionMember(collection) {
+    const config = extractCollectionConfig(collection.payload);
+    const itemNode = renderModelOrder(config.model);
+    const tupleSize = fixedTupleSize(config.min, config.max);
+    const value = tupleSize == null
+        ? tstype('ReadonlyArray<<%= i %>>', { i: itemNode })
+        : tstype('readonly [%= items %]', {
+            items: Array.from({ length: tupleSize }, () => itemNode)
+        });
+    return tsmember('readonly <%= name %>: <%= value %>;', {
+        name: propertyName(collection.name),
+        value
+    });
+}
+function extractCollectionConfig(payload) {
+    if (!('type' in payload)) {
+        return payload;
+    }
+    if (payload.type === 'enable' || payload.type === 'unless') {
+        return extractCollectionConfig(payload.payload);
+    }
+    const branches = Object.values(payload.selectMap).filter((branch) => branch != null);
+    const [first] = branches;
+    if (first == null) {
+        throw new Error(`codegen: collection 'match' has no non-null branch`);
+    }
+    return extractCollectionConfig(first);
+}
+function fixedTupleSize(min, max) {
+    if (min !== max) {
+        return null;
+    }
+    if (!Number.isInteger(min) || min < 0) {
+        return null;
+    }
+    return min;
+}
+function propertyName(name) {
+    if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name)) {
+        return ts.factory.createIdentifier(name);
+    }
+    return ts.factory.createStringLiteral(name);
+}
+function primitiveTypeNode(valueType) {
+    if (valueType === 'string') {
+        return ts.factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword);
+    }
+    if (valueType === 'number') {
+        return ts.factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword);
+    }
+    return ts.factory.createKeywordTypeNode(ts.SyntaxKind.BooleanKeyword);
+}
+function unionOf(members) {
+    const [first, ...rest] = members;
+    if (first == null) {
+        return ts.factory.createKeywordTypeNode(ts.SyntaxKind.NeverKeyword);
+    }
+    if (rest.length === 0) {
+        return first;
+    }
+    return ts.factory.createUnionTypeNode([first, ...rest]);
+}
+function maybeNullable(node, isNullable) {
+    if (!isNullable) {
+        return node;
+    }
+    return ts.factory.createUnionTypeNode([
+        node,
+        ts.factory.createLiteralTypeNode(ts.factory.createNull())
+    ]);
+}
+function pascalCase(name) {
+    const words = name.split(/[\s\-_]+/).filter((word) => word.length > 0);
+    if (words.length === 0) {
+        throw new Error(`codegen: name '${name}' produces an empty type name`);
+    }
+    return words
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join('')
+        .replace(/[^A-Za-z0-9]/g, '');
+}

package/dist/codegen/template.d.ts

@@ -0,0 +1,5 @@
+import type ts from 'typescript';
+type TemplateData = Readonly<Record<string, string | ts.Node | ReadonlyArray<ts.Node>>>;
+export declare function tstype(template: string, data?: TemplateData): ts.TypeNode;
+export declare function tsmember(template: string, data?: TemplateData): ts.TypeElement;
+export {};

package/dist/codegen/template.js

@@ -0,0 +1,17 @@
+import { tsquery } from '@phenomnomnominal/tsquery';
+import { tstemplate } from '@phenomnomnominal/tstemplate';
+import { check } from '../check.js';
+export function tstype(template, data = {}) {
+    const sourceFile = tstemplate(`type __ = ${template};`, data);
+    const [declaration] = tsquery(sourceFile, 'TypeAliasDeclaration');
+    check.truthy(declaration, `tstype invariant: template produced no TypeAliasDeclaration! ❌`);
+    return declaration.type;
+}
+export function tsmember(template, data = {}) {
+    const sourceFile = tstemplate(`type __ = { ${template} };`, data);
+    const [literal] = tsquery(sourceFile, 'TypeLiteral');
+    check.truthy(literal, `tsmember invariant: template produced no TypeLiteral! ❌`);
+    const [member] = literal.members;
+    check.truthy(member, `tsmember invariant: template produced an empty TypeLiteral! ❌`);
+    return member;
+}

package/dist/entities/index.d.ts

@@ -8,8 +8,8 @@ export type { BuilderInstanceOf, BuilderModelGeneric, BuilderModels, BuilderMode
 export { BuilderModel, BuilderModelSchema, BuilderModelSerialisedSchema, model, modelsMerge } from './model/index.js';
 export type { BuilderOptionPayload, BuilderOptions, BuilderOptionSerialised, BuilderOptionsSerialised, BuilderOptionValues, BuilderOptionValuesSerialised, BuilderOptionWhen, BuilderOptionWhenSerialised, BuilderSelectTypeLabels, BuilderSelectTypeSerialised, BuilderSelectTypeValues, BuilderToggleTypeSerialised, BuilderToggleValueType } from './option/index';
 export type { BuilderRefEntities, BuilderRefEntity } from './refs.js';
-export type { BuilderDescription, BuilderDescriptionItem, BuilderUIDescribeSerialised, BuilderUIItem, BuilderUIItems, BuilderUIItemSerialised, BuilderUIItemsSerialised, BuilderUIPageSerialised, BuilderUIPagesSerialised, BuilderUIs, BuilderUIsSerialised, BuilderUISerialised } from './ui/index';
-export type { BuilderCollectionConfigValidated, BuilderCollectionsValidated, BuilderCollectionValidated, BuilderComponentsValidated, BuilderComponentValidated, BuilderComponentVariantsValidated, BuilderInstancesValidated, BuilderInstanceValidated, BuilderModelValidated, BuilderOptionsValidated, BuilderOptionValidated, BuilderUIDescribeValidated, BuilderUIItemsValidated, BuilderUIPageValidated, BuilderUIValidated, BuilderValidated } from './validated';
+export type { BuilderDescription, BuilderDescriptionItem, BuilderUIDescribeSerialised, BuilderUIInputMetadata, BuilderUIInputMetadataSerialised, BuilderUIInputs, BuilderUIInputsSerialised, BuilderUIInputSerialised, BuilderUIItem, BuilderUIItems, BuilderUIItemSerialised, BuilderUIItemsSerialised, BuilderUIPageSerialised, BuilderUIPagesSerialised, BuilderUIs, BuilderUIsSerialised, BuilderUISerialised } from './ui/index';
+export type { BuilderCollectionConfigValidated, BuilderCollectionsValidated, BuilderCollectionValidated, BuilderComponentDetailsValidated, BuilderComponentsValidated, BuilderComponentValidated, BuilderComponentVariantsValidated, BuilderInstancesValidated, BuilderInstanceValidated, BuilderModelValidated, BuilderOptionsValidated, BuilderOptionValidated, BuilderOptionValuesValidated, BuilderUIDescribeValidated, BuilderUIItemsValidated, BuilderUIPageValidated, BuilderUIValidated, BuilderValidated } from './validated';
 export type { BuilderEnableConfig, BuilderMatchConfig, BuilderMatchSelectMap, BuilderUnlessConfig, BuilderWhen, BuilderWhenConfig, BuilderWhenSerialised } from './when';
 export { Builder, builder, BuilderSchema, BuilderSerialisedSchema } from './builder/index.js';
 export { BuilderCollection, BuilderCollectionConfig, BuilderCollectionConfigSchema, BuilderCollectionConfigSerialisedSchema, BuilderCollectionSchema, BuilderCollectionSelectMapSerialisedSchema, BuilderCollectionSerialisedSchema, BuilderCollectionsSerialisedSchema, BuilderCollectionWhenSerialisedSchema, collectionConfig, collectionExpectation, collectionWhen } from './collection/index.js';
@@ -19,5 +19,5 @@ export { BuilderExpectation, BuilderExpectationKindSchema, BuilderExpectationSch
 export { BuilderEntityKindSchema, BuilderEntitySerialisedSchema } from './kind.js';
 export { BuilderOption, BuilderOptionSchema, BuilderOptionSelectMapSerialisedSchema, BuilderOptionSerialisedSchema, BuilderOptionsSerialisedSchema, BuilderOptionValuesSchema, BuilderOptionValuesSerialisedSchema, BuilderOptionWhenSerialisedSchema, BuilderSelectType, BuilderSelectTypeSchema, BuilderSelectTypeSerialisedSchema, BuilderToggleType, BuilderToggleTypeSchema, BuilderToggleTypeSerialisedSchema, optionExpectation, optionValueSchema, optionWhen, select, toggleBoolean, toggleNumber, toggleString } from './option/index.js';
 export { serialise } from './serialise.js';
-export { BuilderDescriptionItemSchema, BuilderDescriptionSchema, BuilderUI, BuilderUIDescribe, BuilderUIDescribeSchema, BuilderUIDescribeSerialisedSchema, BuilderUIItemSerialisedSchema, BuilderUIItemsSerialisedSchema, BuilderUIPage, BuilderUIPages, BuilderUIPageSchema, BuilderUIPageSerialisedSchema, BuilderUIPagesSchema, BuilderUIPagesSerialisedSchema, BuilderUISchema, BuilderUISerialisedSchema, uis } from './ui/index.js';
+export { BuilderDescriptionItemSchema, BuilderDescriptionSchema, BuilderUI, BuilderUIDescribe, BuilderUIDescribeSchema, BuilderUIDescribeSerialisedSchema, BuilderUIInput, BuilderUIInputMetadataSchema, BuilderUIInputSchema, BuilderUIInputSerialisedSchema, BuilderUIInputsSerialisedSchema, BuilderUIItemSerialisedSchema, BuilderUIItemsSerialisedSchema, BuilderUIPage, BuilderUIPages, BuilderUIPageSchema, BuilderUIPageSerialisedSchema, BuilderUIPagesSchema, BuilderUIPagesSerialisedSchema, BuilderUISchema, BuilderUISerialisedSchema, input, uis } from './ui/index.js';
 export { BuilderWhenConfigSchema, BuilderWhenEnableSchema, BuilderWhenMatchSchema, BuilderWhenSerialisedSchema, BuilderWhenUnlessSchema, createWhenFactories, createWhenSerialisedSchema } from './when.js';

package/dist/entities/index.js

@@ -7,5 +7,5 @@ export { BuilderExpectation, BuilderExpectationKindSchema, BuilderExpectationSch
 export { BuilderEntityKindSchema, BuilderEntitySerialisedSchema } from './kind.js';
 export { BuilderOption, BuilderOptionSchema, BuilderOptionSelectMapSerialisedSchema, BuilderOptionSerialisedSchema, BuilderOptionsSerialisedSchema, BuilderOptionValuesSchema, BuilderOptionValuesSerialisedSchema, BuilderOptionWhenSerialisedSchema, BuilderSelectType, BuilderSelectTypeSchema, BuilderSelectTypeSerialisedSchema, BuilderToggleType, BuilderToggleTypeSchema, BuilderToggleTypeSerialisedSchema, optionExpectation, optionValueSchema, optionWhen, select, toggleBoolean, toggleNumber, toggleString } from './option/index.js';
 export { serialise } from './serialise.js';
-export { BuilderDescriptionItemSchema, BuilderDescriptionSchema, BuilderUI, BuilderUIDescribe, BuilderUIDescribeSchema, BuilderUIDescribeSerialisedSchema, BuilderUIItemSerialisedSchema, BuilderUIItemsSerialisedSchema, BuilderUIPage, BuilderUIPages, BuilderUIPageSchema, BuilderUIPageSerialisedSchema, BuilderUIPagesSchema, BuilderUIPagesSerialisedSchema, BuilderUISchema, BuilderUISerialisedSchema, uis } from './ui/index.js';
+export { BuilderDescriptionItemSchema, BuilderDescriptionSchema, BuilderUI, BuilderUIDescribe, BuilderUIDescribeSchema, BuilderUIDescribeSerialisedSchema, BuilderUIInput, BuilderUIInputMetadataSchema, BuilderUIInputSchema, BuilderUIInputSerialisedSchema, BuilderUIInputsSerialisedSchema, BuilderUIItemSerialisedSchema, BuilderUIItemsSerialisedSchema, BuilderUIPage, BuilderUIPages, BuilderUIPageSchema, BuilderUIPageSerialisedSchema, BuilderUIPagesSchema, BuilderUIPagesSerialisedSchema, BuilderUISchema, BuilderUISerialisedSchema, input, uis } from './ui/index.js';
 export { BuilderWhenConfigSchema, BuilderWhenEnableSchema, BuilderWhenMatchSchema, BuilderWhenSerialisedSchema, BuilderWhenUnlessSchema, createWhenFactories, createWhenSerialisedSchema } from './when.js';

package/dist/entities/kind.d.ts

@@ -2,7 +2,7 @@ import type { EntitiesMap } from './serialise';
 import * as v from 'valibot';
 import { entitiesMap } from './serialise.js';
 export type BuilderEntityKind = keyof typeof entitiesMap;
-export declare const BuilderEntityKindSchema: v.PicklistSchema<readonly ("string" | "number" | "boolean" | "builder" | "model" | "ui" | "select" | "toggle" | "paths" | "uiPage" | "uiDescribe" | "uiPages" | "componentDetails" | "collectionConfig" | "expectations" | "uiItems" | "optionWhen" | "componentWhen" | "collectionWhen" | "optionSelectMap" | "componentSelectMap" | "collectionSelectMap" | "path")[], undefined>;
+export declare const BuilderEntityKindSchema: v.PicklistSchema<readonly ("string" | "number" | "boolean" | "builder" | "model" | "ui" | "select" | "toggle" | "path" | "uiPage" | "uiDescribe" | "uiPages" | "uiInput" | "componentDetails" | "collectionConfig" | "expectations" | "uiItems" | "optionWhen" | "componentWhen" | "collectionWhen" | "optionSelectMap" | "componentSelectMap" | "collectionSelectMap" | "paths")[], undefined>;
 export type BuilderEntitySerialised = {
     [Kind in keyof EntitiesMap]: v.InferOutput<EntitiesMap[Kind]['serialised']>;
 }[keyof EntitiesMap];