@olenbetong/appframe-vite 6.14.0 → 6.16.0

package/README.md

@@ -279,11 +279,51 @@ procedures:
 | `fields`      | `string \| string[]` | Fields to include (all if omitted)                                              |
 | `transaction` | `boolean`            | Procedures only. `false` stops the framework wrapping the call in a transaction |
 | `timeout`     | `number`             | Procedures only. Milliseconds before the call is abandoned (default `30000`)    |
+| `returnType`  | `object[] \| string` | Procedures only. The result type; see below                                     |
 
 A top-level `server` key can override the hostname (defaults to `appframe.proxy.hostname` from `package.json`).
 
 **Master/child relationships:** set both `master` and `linkFields` on the child object. The generated data object will include `masterDataObject` and `linkFields` in the `generateApiDataObject(...)` options.
 
+**Procedure result types:** the server only describes a procedure's parameters, so its result is
+typed `{ Table?: unknown[] }` unless `returnType` says otherwise. Never type the result by editing
+the generated file — every regeneration (a `resources.yaml` change seen by the dev server, a
+`git pull --rebase` that touches it, `resources generate`) writes the file from scratch. With
+`returnType` (and `types: true`) the generated file exports the type under the procedure's name,
+next to the parameters type — `procIndexDNA` gets `IndexDNAParams` and `IndexDNAResult` — so
+components import it from the generated file.
+
+`returnType` is either a list of result sets, in the order the procedure returns them (`Table`,
+`Table1`, …; `table` overrides the key), with each field's TypeScript type:
+
+```yaml
+procedures:
+  - id: procIndexDNA
+    resource: astp_Operations_IndexDNA
+    global: true
+    types: true
+    returnType:
+      - fields:
+          - name: IndexName
+            type: string
+          - name: CurrentFF
+            type: number
+      - fields:
+          - name: PageSort
+            type: number
+    output: src/features/IndexDetails/procIndexDNA.ts
+```
+
+or a TypeScript type written out as a string, for anything the list cannot express. It may refer
+to types in the app's `custom.d.ts` through the `Custom.` prefix, which adds the import:
+
+```yaml
+returnType: "Custom.IndexDNAResult"
+```
+
+`procedureReturnTypes` in `types.json`, keyed by the procedure's database name, does the same
+and is used when the entry has no `returnType`.
+
 ## `@olenbetong/appframe-vite/resources` export
 
 Shared code generation utilities for Node.js consumers:

package/lib/appEntry.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Resolves the app's entry module. Apps have no `index.html`: the dev server fetches the
+ * article's HTML from Synergi and injects a `<script type="module">` pointing at this file,
+ * and the production build uses it as the single rolldown input.
+ *
+ * `relative` is a POSIX path from the root, usable as a glob pattern (`optimizeDeps.entries`
+ * takes globs, and an absolute Windows path would be read as one with escapes in it).
+ * The last candidate is returned even when it does not exist, so a missing entry fails
+ * with a resolve error that names the file instead of a vaguer one later on.
+ */
+export declare function getAppEntry(root?: string): {
+    absolute: string;
+    relative: string;
+    url: string;
+};

package/lib/appEntry.js

@@ -0,0 +1,19 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+/** The entry file candidates, in the order they are tried, relative to the app root. */
+const ENTRY_CANDIDATES = ["src/index.tsx", "src/index.ts", "src/index.js"];
+/**
+ * Resolves the app's entry module. Apps have no `index.html`: the dev server fetches the
+ * article's HTML from Synergi and injects a `<script type="module">` pointing at this file,
+ * and the production build uses it as the single rolldown input.
+ *
+ * `relative` is a POSIX path from the root, usable as a glob pattern (`optimizeDeps.entries`
+ * takes globs, and an absolute Windows path would be read as one with escapes in it).
+ * The last candidate is returned even when it does not exist, so a missing entry fails
+ * with a resolve error that names the file instead of a vaguer one later on.
+ */
+export function getAppEntry(root = process.cwd()) {
+    let found = ENTRY_CANDIDATES.find((candidate) => existsSync(resolve(root, candidate)));
+    let relative = found ?? ENTRY_CANDIDATES[ENTRY_CANDIDATES.length - 1];
+    return { absolute: resolve(root, relative), relative, url: `/${relative}` };
+}

package/lib/appframeDataGlobal.js

@@ -19,6 +19,8 @@ export const GLOBAL_EXPORTS = [
     "Procedure",
     "ProcedureAPI",
     "SortOrder",
+    "UploadManager",
+    "UploadTask",
     "generateApiDataHandler",
     "generateApiDataObject",
     "getDefaultClient",

package/lib/build.js

@@ -1,8 +1,8 @@
-import { existsSync } from "node:fs";
 import { readdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { visualizer } from "rollup-plugin-visualizer";
 import { esmExternalRequirePlugin } from "vite";
+import { getAppEntry } from "./appEntry.js";
 import { importJson } from "./importJson.js";
 /**
  * The bare specifiers the 2026 site templates resolve through their import map to the
@@ -38,6 +38,10 @@ export const PLATFORM_EXTERNALS = [
     "highcharts-react-official",
     "mqtt",
     "temporal-polyfill",
+    // The code editor. Its stylesheet and language workers are served next to the entry, not
+    // linked by the template: only the pages that open an editor load them (synergi-react
+    // `CodeEditor` resolves them from the specifier).
+    "monaco-editor",
 ];
 /**
  * The IIFE global each platform specifier is published under (`buildConfig.entries` in the
@@ -68,6 +72,7 @@ export const PLATFORM_GLOBALS = {
     "highcharts-react-official": "SynergiPlatform.highchartsReact",
     mqtt: "SynergiPlatform.mqtt",
     "temporal-polyfill": "SynergiPlatform.temporal",
+    "monaco-editor": "SynergiPlatform.monaco",
 };
 export function usesPlatform(appframe) {
     return appframe?.build?.platform === true;
@@ -94,6 +99,7 @@ export const PLATFORM_UPSTREAM = [
     "highcharts-react-official",
     "mqtt",
     "temporal-polyfill",
+    "monaco-editor",
 ];
 /**
  * Whether the app renders `ToolbarDrawerToggle` (synergi-react) anywhere under `src/`: a plain
@@ -196,16 +202,9 @@ export async function addAppframeBuildConfig(config) {
         sourcemap: true,
     };
     config.plugins = config.plugins ?? [];
-    let entry = resolve(process.cwd(), "./src/index.tsx");
-    if (!existsSync(resolve(entry))) {
-        entry = resolve(process.cwd(), "./src/index.ts");
-    }
-    if (!existsSync(resolve(entry))) {
-        entry = resolve(process.cwd(), "./src/index.js");
-    }
     config.appType = "custom";
     config.build.rolldownOptions = {
-        input: { main: entry },
+        input: { main: getAppEntry().absolute },
         plugins: [
             // Cast visualizer plugin to any to avoid Rollup type version clashes
             visualizer({ filename: "./dist/stats.html", gzipSize: true }),

package/lib/cli-resources-edit.js

@@ -144,7 +144,10 @@ export async function editResource(id) {
         sortOrder = sortInput || undefined;
     }
     let relativeOutput = relative(process.cwd(), resolve(process.cwd(), output)).replace(/\\/g, "/");
+    // Start from the existing entry so settings the wizard does not ask about (returnType,
+    // master, linkFields, timeout, transaction, ...) are kept
     let updatedEntry = {
+        ...entry,
         id: newId,
         resource: entry.resource,
         output: relativeOutput,

package/lib/cli-resources-migrate.js

@@ -182,6 +182,10 @@ function dataObjectToEntry(datasource, fields, outputDir, warnings) {
     if (sortFields.length > 0) {
         entry.sortOrder = sortFields.map((f) => {
             let direction = (f.AscDesc ?? "asc").toLowerCase();
+            // Keep the null placement of AscNullsLast / DescNullsFirst
+            if (direction === "ascnullslast" || direction === "descnullsfirst") {
+                return { field: f.FieldName, direction };
+            }
             return direction.startsWith("desc") ? { field: f.FieldName, direction: "desc" } : { field: f.FieldName };
         });
     }

package/lib/devServer.js

@@ -5,6 +5,7 @@ import { AuthenticationError, authenticate, loginHint, resolveCredentials } from
 import { Client } from "@olenbetong/appframe-data";
 import dotenv from "dotenv";
 import { JSDOM } from "jsdom";
+import { getAppEntry } from "./appEntry.js";
 import { importJson } from "./importJson.js";
 import { getStringCache } from "./localization.js";
 import { diagnoseServerResponse } from "./utils.js";
@@ -68,16 +69,7 @@ export function getProxyRoutes() {
  * @returns
  */
 async function transformArticleHtml(html) {
-    let entry;
-    if (existsSync(resolve(process.cwd(), "./src/index.tsx"))) {
-        entry = "/src/index.tsx";
-    }
-    else if (existsSync(resolve(process.cwd(), "./src/index.ts"))) {
-        entry = "/src/index.ts";
-    }
-    else {
-        entry = "/src/index.js";
-    }
+    let entry = getAppEntry().url;
     let article = appframe.article?.id;
     let { hostname } = await getAppHostname();
     let dom = new JSDOM(html);

package/lib/index.js

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import bodyParser from "body-parser";
 import { watch } from "chokidar";
+import { getAppEntry } from "./appEntry.js";
 import { appframeDataGlobal } from "./appframeDataGlobal.js";
 import { addAppframeBuildConfig, PLATFORM_EXTERNALS, PLATFORM_GLOBALS, PLATFORM_UPSTREAM, platformManifest, usesPlatform, } from "./build.js";
 import { generateFromConfig } from "./cli-resources-generate.js";
@@ -184,6 +185,19 @@ export default function appframe(options = {}) {
                     ...config.server,
                     proxy,
                 };
+                // Apps have no index.html, so the dependency scanner Vite runs at startup has
+                // nothing to crawl (it globs "**/*.html") and skips pre-bundling altogether. Every
+                // dependency is then discovered when a module first imports it: the ones behind
+                // the initial page load are batched, but a lazy route that pulls in a new one
+                // re-runs the optimizer and forces a full reload, which lands back on the page
+                // you navigated from. Crawling from the entry module finds the lazy imports up
+                // front, so the deps are ready before the browser asks for them.
+                if (!config.optimizeDeps?.entries) {
+                    config.optimizeDeps = {
+                        ...config.optimizeDeps,
+                        entries: [getAppEntry().relative],
+                    };
+                }
             }
             return config;
         },

package/lib/procedureReturnType.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/procedureReturnType.test.js

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { getProcedureDefinition } from "./resourceGenerate.js";
+import { entryToCLIOptions } from "./resourcesConfig.js";
+const definition = {
+    Parameters: [{ ParamName: "pIndexID", TypeName: "int", has_default_value: false, is_nullable: false }],
+};
+function generate(returnType) {
+    let options = entryToCLIOptions({
+        id: "procIndexDNA",
+        resource: "astp_Operations_IndexDNA",
+        output: "src/procIndexDNA.ts",
+        global: true,
+        types: true,
+        returnType,
+    }, "example.com");
+    return getProcedureDefinition("astp_Operations_IndexDNA", definition, options);
+}
+describe("procedure return types", () => {
+    it("keeps the untyped default without a returnType", () => {
+        let output = generate(undefined);
+        expect(output).not.toContain("IndexDNAResult");
+        expect(output).toContain("ProcedureAPI<IndexDNAParams, { Table?: unknown[] }>");
+    });
+    it("names a structured returnType after the procedure", () => {
+        let output = generate([
+            { fields: [{ name: "IndexName", type: "string" }] },
+            { fields: [{ name: "PageSort", type: "number" }] },
+        ]);
+        expect(output).toContain("export type IndexDNAResult = { Table: { IndexName: string }[]; Table1: { PageSort: number }[] };");
+        expect(output).toContain("ProcedureAPI<IndexDNAParams, IndexDNAResult>");
+    });
+    it("uses a string returnType as written", () => {
+        let output = generate("Custom.IndexDNAResult");
+        expect(output).toContain("export type IndexDNAResult = Custom.IndexDNAResult;");
+        expect(output).toContain('import type * as Custom from "');
+    });
+    it("does not emit a result type without types", () => {
+        let options = entryToCLIOptions({
+            id: "procIndexDNA",
+            resource: "astp_Operations_IndexDNA",
+            output: "src/procIndexDNA.ts",
+            global: true,
+            returnType: "{ Table: [] }",
+        }, "example.com");
+        let output = getProcedureDefinition("astp_Operations_IndexDNA", definition, options);
+        expect(output).not.toContain("IndexDNAResult");
+    });
+});

package/lib/resourceGenerate.js

@@ -169,6 +169,13 @@ export function parseYamlConfig(fileContent) {
 // ---------------------------------------------------------------------------
 // Code generation helpers
 // ---------------------------------------------------------------------------
+/**
+ * A field name as an object key in generated code, quoted when it is not a valid identifier,
+ * such as a view column named `EU-Neste`.
+ */
+function propertyKey(name) {
+    return /^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name);
+}
 /**
  * Convert Appframe (SQL) data types to typescript/field definition types
  */
@@ -302,7 +309,14 @@ export function getProcedureDefinition(name, procDefinition, options) {
             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[] }"}>` : ""}({
+    // A configured return type gets a name of its own, so components can import it and it
+    // survives every regeneration instead of being written into the output by hand.
+    let resultType = "{ Table?: unknown[] }";
+    if (options.types && options.typesJsonReturnType) {
+        resultType = `${paramTypeName.replace(/Params$/, "")}Result`;
+        output.push(`export type ${resultType} = ${options.typesJsonReturnType};\n`);
+    }
+    output.push(`export const ${procName} = new ${options.global ? "af." : ""}ProcedureAPI${options.types ? `<${paramTypeName}, ${resultType}>` : ""}({
   procedureId: "${name}",
   parameters: ${JSON.stringify(parameters, null, 2)},
   timeout: ${options.timeout ?? 30000}${options.transaction === false ? ",\n  transaction: false" : ""}
@@ -387,7 +401,7 @@ export function getDataObjectDefinition(name, viewDefinition, options) {
                     type += " | null";
                 }
             }
-            fieldTypes += `  ${field.name}: ${type};\n`;
+            fieldTypes += `  ${propertyKey(field.name)}: ${type};\n`;
         }
         types = `export type ${typeName} = {
 ${fieldTypes}}`;
@@ -458,7 +472,7 @@ ${fieldTypes}}`;
                     order = "DescNullsFirst";
                     break;
             }
-            return `{ ${field}: ${sortPrefix}${order} }`;
+            return `{ ${propertyKey(field)}: ${sortPrefix}${order} }`;
         })
             .join(", ");
         parametersOption.push(`sortOrder: [${sortOrder}]`);

package/lib/resourcesConfig.d.ts

@@ -77,8 +77,12 @@ export type ResourceEntry = {
     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[];
+    /**
+     * Procedures only. The result type, emitted as `export type <Name>Result` next to the
+     * parameters type. Either a list of result sets with their fields, or a TypeScript type
+     * written out as a string (which may reference `Custom.*` types from `custom.d.ts`).
+     */
+    returnType?: ReturnTypeTable[] | string;
 };
 export type ResourcesConfig = {
     /** Optional server hostname override (defaults to `appframe.proxy.hostname` from package.json) */

package/lib/resourcesConfig.js

@@ -113,7 +113,11 @@ export function entryToCLIOptions(entry, hostname) {
         where: entry.where,
         fields: arrayOrStringToString(entry.fields) ?? false,
         output: resolve(process.cwd(), entry.output ?? `src/data/${entry.id}.ts`),
-        typesJsonReturnType: entry.returnType ? returnTypeToString(entry.returnType) : undefined,
+        typesJsonReturnType: typeof entry.returnType === "string"
+            ? entry.returnType
+            : entry.returnType
+                ? returnTypeToString(entry.returnType)
+                : undefined,
     };
 }
 /** Convert a `CLIOptions` back to a `ResourceEntry` for saving to YAML. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olenbetong/appframe-vite",
-  "version": "6.14.0",
+  "version": "6.16.0",
   "description": "Tools to use and deploy Vite applications to Appframe",
   "main": "./lib/index.js",
   "type": "module",
@@ -29,25 +29,25 @@
   "author": "Bjørnar Vister Hansen <bvh@olenbetong.no>",
   "license": "MIT",
   "dependencies": {
-    "@olenbetong/appframe-auth": "0.1.0",
-    "@olenbetong/appframe-data": "1.8.2",
+    "@olenbetong/appframe-auth": "^0.1.0",
+    "@olenbetong/appframe-data": "^1.8.3",
     "body-parser": "^2.3.0",
     "chalk": "6.0.1",
     "chokidar": "^5.0.0",
     "commander": "15.0.0",
-    "dotenv": "^18.0.4",
+    "dotenv": "^18.0.8",
     "fuzzy": "^0.1.3",
-    "inquirer": "^14.2.2",
+    "inquirer": "^14.2.4",
     "inquirer-autocomplete-standalone": "^0.8.1",
-    "jsdom": "30.1.1",
+    "jsdom": "30.1.3",
     "rollup-plugin-visualizer": "^7.1.1",
     "yaml": "^2.9.1"
   },
   "devDependencies": {
     "@types/jsdom": "^30.0.0",
-    "@types/node": "26.6.3",
+    "@types/node": "26.6.5",
     "typescript": "7.0.2",
-    "vite": "8.3.1"
+    "vite": "8.3.5"
   },
   "peerDependencies": {
     "vite": ">=8.1.5"