@stonecrop/stonecrop 0.12.8 → 0.13.0

package/dist/registry.js

@@ -0,0 +1,423 @@
+import { getGlobalTriggerEngine } from './field-triggers';
+/**
+ * Stonecrop Registry class
+ * @public
+ */
+export default class Registry {
+    /**
+     * The root Registry instance
+     */
+    static _root;
+    /**
+     * The name of the Registry instance
+     *
+     * @defaultValue 'Registry'
+     */
+    name = 'Registry';
+    /**
+     * The registry property contains a collection of doctypes
+     *
+     * @defaultValue `{}`
+     * @see {@link Doctype}
+     */
+    registry = {};
+    /**
+     * Reverse index: backlink fieldname → list of \{ doctype slug, link fieldname \}.
+     * Multiple doctypes can declare a link with the same backlink name, so each key
+     * maps to an array. Built at schema load time for O(1) ancestor lookups.
+     *
+     * @defaultValue `new Map()`
+     * @internal
+     */
+    _ancestorIndex = new Map();
+    /**
+     * Whether the ancestor index needs rebuilding
+     *
+     * @defaultValue `true`
+     * @internal
+     */
+    _ancestorIndexDirty = true;
+    /**
+     * The Vue router instance
+     * @see {@link https://router.vuejs.org/}
+     */
+    router;
+    /**
+     * Creates a new Registry instance (singleton pattern)
+     * @param router - Optional Vue router instance for route management
+     * @param getMeta - Optional function to fetch doctype metadata from an API
+     */
+    constructor(router, getMeta) {
+        if (Registry._root) {
+            return Registry._root;
+        }
+        Registry._root = this;
+        this.router = router;
+        this.getMeta = getMeta;
+    }
+    /**
+     * The getMeta function fetches doctype metadata from an API based on route context
+     * @see {@link Doctype}
+     */
+    getMeta;
+    /**
+     * Get doctype metadata
+     * @param doctype - The doctype to fetch metadata for
+     * @returns The doctype metadata
+     * @see {@link Doctype}
+     */
+    addDoctype(doctype) {
+        if (!(doctype.slug in this.registry)) {
+            this.registry[doctype.slug] = doctype;
+            this._ancestorIndexDirty = true;
+        }
+        // Register actions (including field triggers) with the field trigger engine
+        const triggerEngine = getGlobalTriggerEngine();
+        // Register under both doctype name and slug to handle different lookup patterns
+        triggerEngine.registerDoctypeActions(doctype.doctype, doctype.actions);
+        if (doctype.slug !== doctype.doctype) {
+            triggerEngine.registerDoctypeActions(doctype.slug, doctype.actions);
+        }
+        if (doctype.component && this.router && !this.router.hasRoute(doctype.doctype)) {
+            this.router.addRoute({
+                path: `/${doctype.slug}`,
+                name: doctype.slug,
+                component: doctype.component,
+            });
+        }
+    }
+    /**
+     * Resolve nested Doctype fields in a schema by embedding child schemas inline.
+     *
+     * Accepts a Doctype and extracts `fields` and `links` internally.
+     * Fields array contains both scalar fields and link fields (with fieldtype: 'Link').
+     * Render order is determined by the order of fields in the fields array.
+     *
+     * For each link field:
+     * - Looks up the corresponding link declaration in `links` by fieldname
+     * - `cardinality: 'noneOrMany'` or `'atLeastOne'`: auto-derives `columns` from the target's schema,
+     *   sets `component` to `link.component ?? 'ATable'`, `config: { view: 'list' }`.
+     * - `cardinality: 'one'` or `'atMostOne'`: embeds the target schema as the entry's
+     *   `schema` property, sets `component` to `link.component ?? 'AForm'`.
+     *
+     * Recurses for deeply nested doctypes. Circular references are protected against.
+     * Returns a new array — does not mutate the original.
+     *
+     * @param doctype - The doctype to resolve
+     * @param visited - Internal — set of already-visited doctype slugs for cycle detection
+     * @returns A new schema array with nested links resolved
+     *
+     * @public
+     */
+    resolveSchema(doctype, visited) {
+        const seen = visited ?? new Set();
+        const slug = doctype.slug;
+        // Prevent circular resolution
+        if (seen.has(slug)) {
+            return doctype.schema ? (Array.isArray(doctype.schema) ? doctype.schema : Array.from(doctype.schema)) : [];
+        }
+        seen.add(slug);
+        // Convert schema to array
+        const schemaArray = doctype.schema
+            ? Array.isArray(doctype.schema)
+                ? doctype.schema
+                : Array.from(doctype.schema)
+            : [];
+        // Build a map of link declarations by fieldname for quick lookup
+        // Use the link's fieldname property if set, otherwise use the key
+        const linksByFieldname = new Map();
+        if (doctype.links) {
+            for (const [key, link] of Object.entries(doctype.links)) {
+                const linkFieldname = link.fieldname ?? key;
+                linksByFieldname.set(linkFieldname, link);
+            }
+        }
+        // Process fields in order: scalar fields copied as-is, link fields resolved
+        const resolvedFields = [];
+        for (const field of schemaArray) {
+            // Check if this field is a link field (fieldtype: 'Link')
+            if ('fieldtype' in field && field.fieldtype === 'Link') {
+                const link = linksByFieldname.get(field.fieldname);
+                if (!link) {
+                    // Link field without corresponding link declaration - copy as-is
+                    resolvedFields.push({ ...field });
+                    continue;
+                }
+                const targetDoctype = this.registry[link.target];
+                if (!targetDoctype) {
+                    // Target not found - copy as-is
+                    resolvedFields.push({ ...field });
+                    continue;
+                }
+                const childSchema = this.resolveSchema(targetDoctype, seen);
+                // Extract properties consumed by resolution; preserve everything else
+                // TODO: options and cardinality are untyped runtime properties on link fields; add them to
+                // FormSchema (or a dedicated link field type) to remove this cast
+                const { fieldtype: _ft, options: _opt, cardinality: _card, ...fieldRest } = field;
+                if (link.cardinality === 'noneOrMany' || link.cardinality === 'atLeastOne') {
+                    // Many relationship — build table config
+                    resolvedFields.push(this.buildTableConfig({ ...fieldRest, label: fieldRest.label || field.fieldname }, childSchema, link.component));
+                }
+                else {
+                    // One relationship — embed form schema
+                    // TODO: remove assertion once resolved link output has a dedicated type separate from input schema
+                    resolvedFields.push({
+                        ...fieldRest,
+                        label: fieldRest.label || field.fieldname,
+                        component: link.component || fieldRest.component || 'AForm',
+                        schema: childSchema,
+                    });
+                }
+            }
+            else if ('schema' in field && Array.isArray(field.schema)) {
+                // Fieldset — recursively resolve nested fields
+                const resolvedChildren = this.resolveFields(field.schema, linksByFieldname, seen);
+                resolvedFields.push({ ...field, schema: resolvedChildren });
+            }
+            else {
+                // Scalar field — copy as-is
+                resolvedFields.push({ ...field });
+            }
+        }
+        seen.delete(slug);
+        return resolvedFields;
+    }
+    /**
+     * Recursively resolve a flat fields array using the provided link context.
+     * Used by resolveSchema to handle fieldset children.
+     * @internal
+     */
+    resolveFields(fields, links, visited) {
+        const resolved = [];
+        for (const field of fields) {
+            if ('fieldtype' in field && field.fieldtype === 'Link') {
+                const link = links.get(field.fieldname);
+                if (!link) {
+                    resolved.push({ ...field });
+                    continue;
+                }
+                const targetDoctype = this.registry[link.target];
+                if (!targetDoctype) {
+                    resolved.push({ ...field });
+                    continue;
+                }
+                const childSchema = this.resolveSchema(targetDoctype, new Set(visited));
+                const { fieldtype: _ft, options: _opt, cardinality: _card, ...fieldRest } = field;
+                if (link.cardinality === 'noneOrMany' || link.cardinality === 'atLeastOne') {
+                    resolved.push(this.buildTableConfig({ ...fieldRest, label: fieldRest.label || field.fieldname }, childSchema, link.component));
+                }
+                else {
+                    // TODO: remove assertion once resolved link output has a dedicated type separate from input schema
+                    resolved.push({
+                        ...fieldRest,
+                        label: fieldRest.label || field.fieldname,
+                        component: link.component || fieldRest.component || 'AForm',
+                        schema: childSchema,
+                    });
+                }
+            }
+            else if ('schema' in field && Array.isArray(field.schema)) {
+                resolved.push({ ...field, schema: this.resolveFields(field.schema, links, visited) });
+            }
+            else {
+                resolved.push({ ...field });
+            }
+        }
+        return resolved;
+    }
+    /**
+     * Build an ATable configuration from a field and child schema.
+     * Data-model properties from the source field are preserved via the spread `field` argument.
+     * @internal
+     */
+    buildTableConfig(field, childSchema, component) {
+        const resolved = {
+            ...field,
+            fieldname: field.fieldname,
+            component: component || field.component || 'ATable',
+            columns: field.columns,
+            config: field.config,
+        };
+        if (!resolved.columns) {
+            resolved.columns = childSchema
+                .filter(childField => 'fieldtype' in childField)
+                .map(childField => ({
+                name: childField.fieldname,
+                label: ('label' in childField && childField.label) || childField.fieldname,
+                fieldtype: 'fieldtype' in childField ? childField.fieldtype : 'Data',
+                align: 'align' in childField ? childField.align : 'left',
+                edit: 'edit' in childField ? childField.edit : true,
+                width: ('width' in childField && childField.width) || '20ch',
+            }));
+        }
+        if (!resolved.config) {
+            resolved.config = { view: 'list' };
+        }
+        return resolved;
+    }
+    /**
+     * Initialize a new record with default values based on a schema.
+     *
+     * @remarks
+     * Creates a plain object with keys from the schema's fieldnames and default values
+     * derived from each field's `fieldtype`:
+     * - Data, Text → `''`
+     * - Check → `false`
+     * - Int, Float, Decimal, Currency, Quantity → `0`
+     * - JSON → `{}`
+     * - Doctype with `cardinality: 'noneOrMany'` or `'atLeastOne'` → `[]`
+     * - Doctype without `cardinality` or `cardinality: 'one'` → recursively initializes nested record
+     * - All others → `null`
+     *
+     * For Doctype fields with a resolved `schema` array (cardinality: 'one'), recursively
+     * initializes the nested record.
+     *
+     * @param schema - The schema array to derive defaults from
+     * @returns A plain object with default values for each field
+     *
+     * @example
+     * ```ts
+     * const defaults = registry.initializeRecord(addressSchema)
+     * // { street: '', city: '', state: '', zip_code: '' }
+     * ```
+     *
+     * @public
+     */
+    initializeRecord(schema) {
+        const record = {};
+        schema.forEach(field => {
+            const fieldtype = 'fieldtype' in field ? field.fieldtype : 'Data';
+            const cardinality = 'cardinality' in field ? field.cardinality : undefined;
+            // 1:many — cardinality signals an array
+            if (cardinality === 'noneOrMany' || cardinality === 'atLeastOne') {
+                record[field.fieldname] = [];
+                return;
+            }
+            // Resolved 1:many table entry — structural detection via columns
+            // TODO: replace 'columns' presence check with a type discriminant on SchemaTypes once one exists
+            if ('columns' in field) {
+                record[field.fieldname] = [];
+                return;
+            }
+            // Resolved 1:1 link entry — has schema property (e.g., FieldsetSchema with nested schema)
+            if ('schema' in field && Array.isArray(field.schema)) {
+                record[field.fieldname] = this.initializeRecord(field.schema);
+                return;
+            }
+            switch (fieldtype) {
+                case 'Data':
+                case 'Text':
+                case 'Code':
+                    record[field.fieldname] = '';
+                    break;
+                case 'Check':
+                    record[field.fieldname] = false;
+                    break;
+                case 'Int':
+                case 'Float':
+                case 'Decimal':
+                case 'Currency':
+                case 'Quantity':
+                    record[field.fieldname] = 0;
+                    break;
+                case 'JSON':
+                    record[field.fieldname] = {};
+                    break;
+                default:
+                    record[field.fieldname] = null;
+            }
+        });
+        return record;
+    }
+    /**
+     * Get a registered doctype by slug
+     * @param slug - The doctype slug to look up
+     * @returns The Doctype instance if found, or undefined
+     * @public
+     */
+    getDoctype(slug) {
+        return this.registry[slug];
+    }
+    /**
+     * Get all links declared on a doctype.
+     *
+     * @param doctypeSlug - The doctype slug to get links for
+     * @returns Array of link declarations with fieldname, or empty array if none
+     *
+     * @example
+     * ```ts
+     * const links = registry.getDescendantLinks('recipe')
+     * // [{ fieldname: 'tasks', target: 'recipe-task', cardinality: 'noneOrMany', backlink: 'recipe' }]
+     * ```
+     *
+     * @public
+     */
+    getDescendantLinks(doctypeSlug) {
+        const doctype = this.registry[doctypeSlug];
+        if (!doctype?.links)
+            return [];
+        return Object.entries(doctype.links).map(([fieldname, link]) => ({
+            ...link,
+            fieldname,
+        }));
+    }
+    /**
+     * Get links on other doctypes that target the given doctype.
+     *
+     * @param doctypeSlug - The doctype slug to find ancestor links for
+     * @returns Array of link declarations with fieldname and declaring doctype slug, or empty array
+     *
+     * @example
+     * ```ts
+     * const ancestors = registry.getAncestorLinks('recipe-task')
+     * // [{ fieldname: 'tasks', target: 'recipe-task', cardinality: 'noneOrMany', backlink: 'recipe', doctype: 'recipe' }]
+     * ```
+     *
+     * @public
+     */
+    getAncestorLinks(doctypeSlug) {
+        this._ensureAncestorIndex();
+        const results = [];
+        for (const [_backlink, entries] of this._ancestorIndex) {
+            for (const { slug: declaringSlug, fieldname } of entries) {
+                const declaringDoctype = this.registry[declaringSlug];
+                if (!declaringDoctype?.links)
+                    continue;
+                const link = declaringDoctype.links[fieldname];
+                if (link?.target === doctypeSlug) {
+                    results.push({
+                        ...link,
+                        fieldname,
+                        doctype: declaringSlug,
+                    });
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * Ensure the ancestor index is up to date
+     * @internal
+     */
+    _ensureAncestorIndex() {
+        if (!this._ancestorIndexDirty)
+            return;
+        this._ancestorIndexDirty = false;
+        this._ancestorIndex.clear();
+        for (const [slug, doctype] of Object.entries(this.registry)) {
+            if (!doctype.links)
+                continue;
+            for (const [fieldname, link] of Object.entries(doctype.links)) {
+                if (link.backlink) {
+                    const existing = this._ancestorIndex.get(link.backlink);
+                    if (existing) {
+                        existing.push({ slug, fieldname });
+                    }
+                    else {
+                        this._ancestorIndex.set(link.backlink, [{ slug, fieldname }]);
+                    }
+                }
+            }
+        }
+    }
+}