@olenbetong/appframe-vite 6.1.2 → 6.3.0

package/lib/resourceGenerate.js

@@ -0,0 +1,569 @@
+import { exec } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+import { importJson } from "./importJson.js";
+const execAsync = promisify(exec);
+// ---------------------------------------------------------------------------
+// Biome formatting
+// ---------------------------------------------------------------------------
+/**
+ * Format a file with Biome if available. Searches for `biome` in the nearest
+ * node_modules/.bin up from cwd, then falls back to the global PATH.
+ * Silently skips if Biome is not found or formatting fails.
+ */
+export async function formatWithBiome(filePath) {
+    let biomeBin = null;
+    let current = resolve(process.cwd());
+    while (true) {
+        let candidate = join(current, "node_modules", ".bin", "biome");
+        let candidateCmd = `${candidate}.cmd`;
+        if (existsSync(candidateCmd)) {
+            biomeBin = candidateCmd;
+            break;
+        }
+        if (existsSync(candidate)) {
+            biomeBin = candidate;
+            break;
+        }
+        let parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    let bin = biomeBin ?? "biome";
+    try {
+        await execAsync(`"${bin}" format --write "${resolve(filePath)}"`);
+    }
+    catch {
+        // Biome not available or not applicable — silently skip
+    }
+}
+// ---------------------------------------------------------------------------
+// YAML config block
+// ---------------------------------------------------------------------------
+/** Options that hold comma-separated lists and should be emitted as YAML lists. */
+const LIST_KEYS = new Set(["fields", "sortOrder", "linkFields", "aggregates", "groupBy", "overrides"]);
+/**
+ * Serialize the generation options to a `/* af:config ... *\/` YAML comment block.
+ * List-type options (fields, sortOrder, etc.) are emitted as proper YAML lists.
+ */
+export function buildYamlConfig(resource, options) {
+    let lines = ["/* af:config", `resource: ${resource}`];
+    const order = [
+        "id",
+        "types",
+        "global",
+        "maxRecords",
+        "sortOrder",
+        "permissions",
+        "master",
+        "linkFields",
+        "expose",
+        "dynamic",
+        "unique",
+        "overrides",
+        "distinct",
+        "aggregates",
+        "groupBy",
+        "where",
+        "fields",
+    ];
+    for (let key of order) {
+        let value = options[key];
+        if (value === undefined || value === null || value === "" || value === false)
+            continue;
+        if (key === "fields" && value === true)
+            continue;
+        if (LIST_KEYS.has(key) && typeof value === "string") {
+            let items = value.split(",").filter(Boolean);
+            lines.push(`${key}:`);
+            for (let item of items) {
+                lines.push(`  - ${item}`);
+            }
+        }
+        else {
+            lines.push(`${key}: ${value}`);
+        }
+    }
+    lines.push("*/");
+    return lines.join("\n");
+}
+/**
+ * Find and parse the `/* af:config ... *\/` block from generated file content.
+ * Returns `{ resource, options }` or `null` if no block is found.
+ */
+export function parseYamlConfig(fileContent) {
+    let startMarker = "/* af:config\n";
+    let endMarker = "\n*/";
+    let startIdx = fileContent.indexOf(startMarker);
+    if (startIdx === -1)
+        return null;
+    let blockStart = startIdx + startMarker.length;
+    let endIdx = fileContent.indexOf(endMarker, blockStart);
+    if (endIdx === -1)
+        return null;
+    let block = fileContent.slice(blockStart, endIdx);
+    let lines = block.split("\n");
+    let resource = "";
+    let raw = {};
+    let currentListKey = null;
+    for (let line of lines) {
+        if (line.startsWith("  - ") && currentListKey) {
+            let arr = raw[currentListKey];
+            if (Array.isArray(arr)) {
+                arr.push(line.slice(4));
+            }
+            continue;
+        }
+        let colonIdx = line.indexOf(": ");
+        if (colonIdx === -1 && line.endsWith(":")) {
+            let key = line.slice(0, -1);
+            raw[key] = [];
+            currentListKey = key;
+            continue;
+        }
+        currentListKey = null;
+        if (colonIdx !== -1) {
+            let key = line.slice(0, colonIdx);
+            let value = line.slice(colonIdx + 2);
+            raw[key] = value;
+        }
+    }
+    resource = raw["resource"];
+    if (!resource)
+        return null;
+    function str(key) {
+        let v = raw[key];
+        if (Array.isArray(v))
+            return v.join(",");
+        return v;
+    }
+    function bool(key) {
+        let v = raw[key];
+        if (v === "true")
+            return true;
+        if (v === "false")
+            return false;
+        return undefined;
+    }
+    function list(key) {
+        let v = raw[key];
+        if (Array.isArray(v))
+            return v.join(",");
+        if (typeof v === "string")
+            return v;
+        return undefined;
+    }
+    let options = {
+        server: "dev.obet.no",
+        id: (str("id") ?? "dsDataObject"),
+        global: bool("global") ?? false,
+        dynamic: bool("dynamic") ?? false,
+        types: bool("types"),
+        maxRecords: str("maxRecords"),
+        sortOrder: list("sortOrder"),
+        permissions: str("permissions"),
+        master: str("master"),
+        linkFields: list("linkFields"),
+        expose: (() => {
+            let v = raw["expose"];
+            if (v === "true")
+                return true;
+            if (v === "false" || v === undefined)
+                return undefined;
+            return v;
+        })(),
+        unique: str("unique"),
+        overrides: list("overrides"),
+        distinct: bool("distinct"),
+        aggregates: list("aggregates"),
+        groupBy: list("groupBy"),
+        where: str("where"),
+        fields: list("fields") ?? false,
+    };
+    return { resource, options };
+}
+// ---------------------------------------------------------------------------
+// Code generation helpers
+// ---------------------------------------------------------------------------
+/**
+ * Convert Appframe (SQL) data types to typescript/field definition types
+ */
+function afTypeToTsType(type, dateStyle = false) {
+    switch (type) {
+        case "bigint":
+            return "bigint";
+        case "int":
+        case "decimal":
+        case "smallint":
+        case "tinyint":
+        case "float":
+        case "numeric":
+            return "number";
+        case "bit":
+            return "boolean";
+        case "datetime2":
+        case "datetime":
+        case "smalldatetime":
+        case "date":
+            if (dateStyle === "ts") {
+                return "Date";
+            }
+            else if (dateStyle === "ts-proc") {
+                return "string | Date";
+            }
+            else {
+                return type === "date" ? "date" : "datetime";
+            }
+        default:
+            return "string";
+    }
+}
+/**
+ * Walk from startDir up toward stopDir (inclusive) looking for custom.d.ts or custom.ts.
+ * Returns the absolute path without extension, or null if not found.
+ */
+function findCustomDts(startDir, stopDir) {
+    let current = resolve(startDir);
+    let stop = resolve(stopDir);
+    while (true) {
+        for (let name of ["custom.d.ts", "custom.ts"]) {
+            let candidate = resolve(current, name);
+            if (existsSync(candidate)) {
+                return candidate.replace(/\.(d\.ts|ts)$/, "");
+            }
+        }
+        if (current === stop)
+            break;
+        let parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return null;
+}
+/**
+ * Compute the relative import specifier for "custom" from the given output file.
+ * Returns a POSIX-style path (e.g. "../custom" or "./custom").
+ */
+export function getCustomImportPath(outputPath) {
+    let outputDir = dirname(resolve(outputPath));
+    let found = findCustomDts(outputDir, process.cwd());
+    if (!found) {
+        return "./custom";
+    }
+    let rel = relative(outputDir, found).split(sep).join("/");
+    if (!rel.startsWith(".")) {
+        rel = `./${rel}`;
+    }
+    return rel;
+}
+export function getProcedureDefinition(name, procDefinition, options) {
+    let parameters = [];
+    let typeOverrides = {};
+    if (options.typesJsonParamOverrides) {
+        Object.assign(typeOverrides, options.typesJsonParamOverrides);
+    }
+    if (options.overrides) {
+        let overrides = options.overrides.split(",");
+        for (let override of overrides) {
+            let [param, type] = override.split(":");
+            typeOverrides[param] = type;
+        }
+    }
+    for (let parameter of procDefinition.Parameters) {
+        parameters.push({
+            name: parameter.ParamName,
+            type: afTypeToTsType(parameter.TypeName, "field"),
+            hasDefault: parameter.has_default_value,
+            required: !parameter.has_default_value && !parameter.is_nullable,
+        });
+    }
+    let output = [];
+    if (!options.global) {
+        output.push(`import { ProcedureAPI } from "@olenbetong/appframe-data";`);
+        if (options.expose) {
+            output.push(`import { expose } from "@olenbetong/appframe-core";`);
+        }
+        output.push("");
+    }
+    let paramTypeName = "ProcParams";
+    let procName = "proc";
+    if (options.id) {
+        procName = options.id;
+        paramTypeName = `${options.id}Params`;
+        if (paramTypeName.startsWith("proc")) {
+            paramTypeName = paramTypeName.substring(4);
+        }
+    }
+    if (options.types) {
+        if (procDefinition.Parameters.length > 0) {
+            let typeOutput = [`export type ${paramTypeName} = {`];
+            for (let parameter of procDefinition.Parameters) {
+                let type = typeOverrides[parameter.ParamName];
+                let name = parameter.ParamName;
+                if (!type) {
+                    type = afTypeToTsType(parameter.TypeName, "ts-proc");
+                }
+                if (parameter.has_default_value || parameter.is_nullable) {
+                    type += " | null";
+                    name += "?";
+                }
+                typeOutput.push(`\t${name}: ${type}`);
+            }
+            typeOutput.push("};");
+            output.push(typeOutput.join("\n"));
+            output.push("");
+        }
+        else {
+            output.push(`export type ${paramTypeName} = null | undefined | Record<string, unknown>;\n`);
+        }
+    }
+    output.push(`export const ${procName} = new ${options.global ? "af." : ""}ProcedureAPI${options.types ? `<${paramTypeName}, ${options.typesJsonReturnType ?? "{ Table?: unknown[] }"}>` : ""}({
+  procedureId: "${name}",
+  parameters: ${JSON.stringify(parameters, null, 2)},
+  timeout: 30000
+});`);
+    if (options.expose) {
+        output.push("");
+        output.push(`${options.global ? "af.common." : ""}expose("af.article.procedures.${procName}", ${procName}, { overwrite: true });`);
+    }
+    let outputStr = output.join("\n");
+    if (outputStr.includes("Custom.")) {
+        let customPath = options.output ? getCustomImportPath(options.output) : "./custom";
+        if (options.global) {
+            outputStr = `import type * as Custom from "${customPath}";\n${outputStr}`;
+        }
+        else {
+            let firstNewline = outputStr.indexOf("\n");
+            outputStr =
+                `${outputStr.substring(0, firstNewline + 1)}import type * as Custom from "${customPath}";\n` +
+                    outputStr.substring(firstNewline + 1);
+        }
+    }
+    return outputStr;
+}
+export function getDataObjectDefinition(name, viewDefinition, options) {
+    let fields = [];
+    let includeFields = typeof options.fields === "string" ? (options.fields?.split(",").filter((f) => !!f) ?? []) : [];
+    let aggregates = {};
+    if (options.aggregates) {
+        for (let aggregateDef of options.aggregates.split(",")) {
+            let [field, aggregate] = aggregateDef.split(":");
+            aggregates[field] = aggregate;
+        }
+    }
+    for (let field of viewDefinition.Parameters) {
+        if (includeFields.length > 0 && !includeFields.includes(field.Name)) {
+            continue;
+        }
+        let fieldDefinition = {
+            name: field.Name,
+            type: field.DataType,
+            nullable: field.Nullable,
+        };
+        if (field.HasDefault) {
+            fieldDefinition.hasDefault = true;
+        }
+        if (field.Computed) {
+            fieldDefinition.computed = true;
+        }
+        if (field.Identity) {
+            fieldDefinition.identity = true;
+        }
+        if (aggregates[field.Name]) {
+            fieldDefinition.aggregate = aggregates[field.Name];
+        }
+        fields.push(fieldDefinition);
+    }
+    let api = "generateApiDataObject";
+    let types = "";
+    let typeName = `${options.id}Record`;
+    let typeOverrides = {};
+    if (options.typesJsonParamOverrides) {
+        Object.assign(typeOverrides, options.typesJsonParamOverrides);
+    }
+    if (options.overrides) {
+        let overrides = options.overrides.split(",");
+        for (let override of overrides) {
+            let [param, type] = override.split(":");
+            typeOverrides[param] = type;
+        }
+    }
+    if (typeName.startsWith("ds")) {
+        typeName = typeName.substring(2);
+    }
+    if (options.types) {
+        api = `generateApiDataObject<${typeName}>`;
+        let fieldTypes = "";
+        for (let field of fields) {
+            let type = typeOverrides[field.name];
+            if (!type) {
+                type = afTypeToTsType(field.type, "ts");
+                if (field.nullable) {
+                    type += " | null";
+                }
+            }
+            fieldTypes += `  ${field.name}: ${type};\n`;
+        }
+        types = `export type ${typeName} = {
+${fieldTypes}}`;
+    }
+    if (options.global) {
+        api = `af.data.${api}`;
+    }
+    let output = "";
+    if (!options.global) {
+        output += `import { generateApiDataObject${options.sortOrder ? ", SortOrder" : ""} } from "@olenbetong/appframe-data";`;
+        if (options.expose) {
+            output += `\nimport { expose } from "@olenbetong/appframe-core";`;
+        }
+        output += "\n\n";
+    }
+    if (options.master && options.master.indexOf(":") > 0) {
+        let [name, path] = options.master.split(":");
+        output += `import { ${name} } from "${path}";\n\n`;
+    }
+    if (options.types) {
+        output += `${types}\n\n`;
+    }
+    let linkFields = "";
+    let dsOptions = [];
+    dsOptions.push(`resource: "${name}"`);
+    if (options.unique) {
+        dsOptions.push(`uniqueName: "${options.unique}"`);
+    }
+    dsOptions.push(`id: "${options.id}"`);
+    if (options.master && options.linkFields) {
+        dsOptions.push(`masterDataObject: ${options.master.split(":")[0]}`);
+        let fields = options.linkFields.split(",");
+        linkFields = `linkFields: {\n\t\t${fields
+            .map((field) => {
+            let [thisField, masterField] = field.split(":");
+            return `${thisField}: "${masterField ?? thisField}",`;
+        })
+            .join("\n\t\t")}\n\t}`;
+        dsOptions.push(linkFields);
+    }
+    dsOptions.push(`allowUpdate: ${options.permissions?.includes("U") ?? false}`);
+    dsOptions.push(`allowInsert: ${options.permissions?.includes("I") ?? false}`);
+    dsOptions.push(`allowDelete: ${options.permissions?.includes("D") ?? false}`);
+    dsOptions.push(`dynamicLoading: ${options.dynamic || false}`);
+    let fieldsOption = fields.map((field) => ({
+        ...field,
+        type: afTypeToTsType(field.type, "field"),
+    }));
+    dsOptions.push(`fields: ${JSON.stringify(fieldsOption, null, 2).split("\n").join("\n\t")}`);
+    let parametersOption = [`maxRecords: ${options.maxRecords}`];
+    if (options.sortOrder) {
+        let sorts = options.sortOrder.split(",");
+        let sortPrefix = options.global ? "af.data.SortOrder." : "SortOrder.";
+        let sortOrder = sorts
+            .map((sort) => {
+            let [field, order = "asc"] = sort.split(":");
+            switch (order.toLocaleLowerCase()) {
+                case "asc":
+                    order = "Asc";
+                    break;
+                case "desc":
+                    order = "Desc";
+                    break;
+                case "ascnullslast":
+                    order = "AscNullsLast";
+                    break;
+                case "descnullsfirst":
+                    order = "DescNullsFirst";
+                    break;
+            }
+            return `{ ${field}: ${sortPrefix}${order} }`;
+        })
+            .join(", ");
+        parametersOption.push(`sortOrder: [${sortOrder}]`);
+    }
+    if (options.groupBy) {
+        parametersOption.push(`groupBy: ${JSON.stringify(options.groupBy.split(","))}`);
+    }
+    if (options.where) {
+        parametersOption.push(`whereClause: "${options.where}"`);
+    }
+    if (options.distinct) {
+        parametersOption.push(`distinctRows: true`);
+    }
+    dsOptions.push(`parameters: {\n\t\t${parametersOption.join(",\n\t\t")}\n\t}`);
+    output += `export const ${options.id} = ${api}({
+  ${dsOptions.join(",\n\t")}
+});
+`;
+    if (options.expose) {
+        let id = typeof options.expose === "string" ? options.expose : options.id;
+        if (options.global) {
+            output += `\naf.common.expose("af.article.dataObjects.${id}", ${options.id}, { overwrite: true });`;
+        }
+        else {
+            output += `\nexpose("af.article.dataObjects.${id}", ${options.id}, { overwrite: true });`;
+        }
+    }
+    if (output.includes("Custom.")) {
+        let customPath = options.output ? getCustomImportPath(options.output) : "./custom";
+        if (options.global) {
+            output = `import type * as Custom from "${customPath}";\n${output}`;
+        }
+        else {
+            let firstNewline = output.indexOf("\n");
+            output =
+                `${output.substring(0, firstNewline + 1)}import type * as Custom from "${customPath}";\n` +
+                    output.substring(firstNewline + 1);
+        }
+    }
+    return output;
+}
+// ---------------------------------------------------------------------------
+// Server interaction
+// ---------------------------------------------------------------------------
+/**
+ * Fetch the resource definition from an authenticated Appframe client.
+ */
+export async function fetchResourceDefinition(client, resourceName) {
+    let response = await client.fetch("/api/data", {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+        },
+        body: JSON.stringify({
+            operation: "resource-definition",
+            resourceName,
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch resource definition for '${resourceName}': ${response.status} ${response.statusText}`);
+    }
+    const json = await response.json();
+    return json.success ?? json;
+}
+/**
+ * Fetch the resource definition from the server, read types.json overrides, and
+ * return the generated TypeScript content string (without any header comment).
+ *
+ * @param resourceName - Pre-resolved resource database object ID (e.g. `aviw_QA_Documents`)
+ * @param options - Generation options
+ * @param client - Authenticated Appframe client
+ */
+export async function fetchAndGenerate(resourceName, options, client) {
+    let definition = await fetchResourceDefinition(client, resourceName);
+    definition.Parameters = (definition.Parameters ?? []).filter((p) => !["CUT", "CDL"].includes(p.Name));
+    let typesJson = {};
+    try {
+        typesJson = await importJson("./types.json", true);
+    }
+    catch {
+        // no types.json — that's fine
+    }
+    options.typesJsonParamOverrides = typesJson.parameterTypes?.[resourceName] ?? {};
+    // Structured returnType from resources.yaml takes precedence over the raw types.json string
+    options.typesJsonReturnType = options.typesJsonReturnType ?? typesJson.procedureReturnTypes?.[resourceName] ?? null;
+    return definition.ObjectType === "V"
+        ? getDataObjectDefinition(resourceName, definition, options)
+        : getProcedureDefinition(resourceName, definition, options);
+}

package/lib/resourcesConfig.d.ts

@@ -0,0 +1,83 @@
+import type { CLIOptions } from "./resourceGenerate.js";
+export type ReturnTypeField = {
+    /** TypeScript field name */
+    name: string;
+    /** TypeScript type, e.g. `string`, `number | null`, `Date` */
+    type: string;
+};
+export type ReturnTypeTable = {
+    /** Property key when multiple result-sets are returned. Omit for single-table procedures. */
+    table?: string;
+    fields: ReturnTypeField[];
+};
+/**
+ * Build an inline TypeScript type string from a structured returnType definition.
+ *
+ * The server always returns a DataSet serialized as `{ Table: T[], Table1: U[], ... }`.
+ * The first table is always `"Table"`, subsequent ones are `"Table1"`, `"Table2"`, etc.
+ * An explicit `table` name on the entry overrides the auto-generated key (for procedures
+ * that assign custom DataTable.TableName values).
+ */
+export declare function returnTypeToString(returnType: ReturnTypeTable[]): string;
+export type ResourceEntry = {
+    /** Data object or procedure identifier used in the generated code (e.g. `dsAccountGroups`) */
+    id: string;
+    /** Database object ID to fetch the definition from (e.g. `atbv_Accounting_SubsidiaryLedgerGroups`) */
+    resource: string;
+    /** Output file path relative to the project root (e.g. `src/data/dsAccountGroups.ts`) */
+    output: string;
+    /** Use `af.data.generateApiDataObject` / `new af.ProcedureAPI` globals instead of imports */
+    global?: boolean;
+    /** Emit TypeScript type definitions */
+    types?: boolean;
+    /** Permissions to set: I = insert, U = update, D = delete (e.g. `IUD`) */
+    permissions?: string;
+    /** Maximum records to fetch (default `50`; use `-1` for all) */
+    maxRecords?: number;
+    /** Sort order as a list of sort objects */
+    sortOrder?: Array<{
+        field: string;
+        direction?: string;
+    }>;
+    /** Name of master data object (optionally `name:importPath` to import from another file) */
+    master?: string;
+    /** Link fields to master data object (comma-separated or array) */
+    linkFields?: string | string[];
+    /** Expose the object on `af.article.dataObjects` / `af.article.procedures` */
+    expose?: boolean | string;
+    /** Enable dynamic loading */
+    dynamic?: boolean;
+    /** Unique table name for update/delete */
+    unique?: string;
+    /** Type overrides for fields/parameters: comma-separated or array of `field:type` */
+    overrides?: string | string[];
+    /** Fetch distinct rows */
+    distinct?: boolean;
+    /** Aggregate bindings for non-grouped fields */
+    aggregates?: Array<{
+        field: string;
+        aggregate: string;
+    }>;
+    /** Group-by fields */
+    groupBy?: string[];
+    /** Initial where clause */
+    where?: string;
+    /** Fields to include: comma-separated or array of field names */
+    fields?: string | string[];
+    /** Structured return type definition for procedures (generates inline TS type) */
+    returnType?: ReturnTypeTable[];
+};
+export type ResourcesConfig = {
+    /** Optional server hostname override (defaults to `appframe.proxy.hostname` from package.json) */
+    server?: string;
+    dataObjects?: ResourceEntry[];
+    procedures?: ResourceEntry[];
+};
+export declare const RESOURCES_CONFIG_FILE = "resources.yaml";
+export declare function getResourcesConfigPath(filePath?: string): string;
+export declare function readResourcesConfig(filePath?: string): Promise<ResourcesConfig>;
+export declare function writeResourcesConfig(config: ResourcesConfig, filePath?: string): Promise<void>;
+/** Convert a `ResourceEntry` into a `CLIOptions`-compatible object for code generation. */
+export declare function entryToCLIOptions(entry: ResourceEntry, hostname: string): CLIOptions;
+/** Convert a `CLIOptions` back to a `ResourceEntry` for saving to YAML. */
+export declare function cliOptionsToEntry(resource: string, options: CLIOptions): ResourceEntry;