@amerilux/netsuite-api 0.6.1 → 0.6.2

package/README.md

@@ -232,6 +232,8 @@ export const { getInputData, map, summarize } = defineJob({
 
 Each stage is then a file named after the stage NetSuite calls, holding the work and the shapes on its own boundary — open map.ts to see what the map stage does:
 
+Only the result has to be a shape the client can carry, because it is the only one a browser is handed. The items a run is planned into are the stage's own working types and stay on the server, so they may be built on whatever the server has — a carrier's API request, a customer's configuration — and the generator does not ask them to be carryable.
+
 ```ts
 // api/src/jobs/closeStaleOrders/getInputData.ts
 import { listStaleOrders, type StaleOrder } from '../../services/staleOrderService';

package/dist-tooling/controllerReader.d.ts

@@ -10,6 +10,8 @@ import ts from 'typescript';
 export interface ControllerProblem {
     filePath: string;
     message: string;
+    /** The type the problem is about, when it is about one: what lets a job drop a problem its result never reaches. */
+    about?: string;
 }
 export interface EndpointSignature {
     name: string;

package/dist-tooling/emit.d.ts

@@ -75,6 +75,16 @@ export declare function emitClientIndexModule(controllers: EmittedController[],
 export declare function sortJobs(jobs: EmittedJob[]): EmittedJob[];
 /** A job's module: the shapes a run is started with and ends in, and the types they are built from. */
 export declare function emitJobModule({ contract, sourceLabel, inlinedTypes }: EmittedJob): string;
+/**
+ * The declared shapes a type names, and the shapes those name in turn: what a module has to carry for the
+ * type to stand on its own. A name with no declaration here belongs to the package or to the language, and
+ * the type import that brought it is what carries it.
+ *
+ * Every name the walk reaches is in the answer, including one nothing declares: a caller asking whether a
+ * type matters to the wire needs the names that could not be resolved as much as the ones that could. What
+ * is emitted is filtered against declarations, so the unresolved names add nothing to a module.
+ */
+export declare function findTypesReachedBy(type: string, ownDeclarations: TypeDeclaration[], inlinedTypes: InlinedTypeSection[]): Set<string>;
 /** The jobs index: every job module under the job's name, reached as `jobs.<name>` from the client index. */
 export declare function emitJobsIndexModule(jobs: EmittedJob[], options: {
     jobsLabel: string;

package/dist-tooling/emit.js

@@ -146,8 +146,12 @@ export function emitJobModule({ contract, sourceLabel, inlinedTypes }) {
  * The declared shapes a type names, and the shapes those name in turn: what a module has to carry for the
  * type to stand on its own. A name with no declaration here belongs to the package or to the language, and
  * the type import that brought it is what carries it.
+ *
+ * Every name the walk reaches is in the answer, including one nothing declares: a caller asking whether a
+ * type matters to the wire needs the names that could not be resolved as much as the ones that could. What
+ * is emitted is filtered against declarations, so the unresolved names add nothing to a module.
  */
-function findTypesReachedBy(type, ownDeclarations, inlinedTypes) {
+export function findTypesReachedBy(type, ownDeclarations, inlinedTypes) {
     const declarationsByName = new Map();
     for (const section of inlinedTypes)
         for (const declaration of section.declarations)
@@ -160,10 +164,10 @@ function findTypesReachedBy(type, ownDeclarations, inlinedTypes) {
         const name = pending.shift();
         if (carried.has(name))
             continue;
+        carried.add(name);
         const text = declarationsByName.get(name);
         if (text === undefined)
             continue;
-        carried.add(name);
         pending.push(...readReferencedNames(text, 'declaration'));
     }
     return carried;

package/dist-tooling/generate.js

@@ -1,7 +1,7 @@
 import * as nodePath from 'node:path';
 import { resolveInlineTypesFile, resolveJobRunFieldIds } from './config.js';
 import { isControllerFileName, readControllerContract } from './controllerReader.js';
-import { CLIENT_INDEX_FILE_NAME, JOBS_INDEX_FILE_NAME, controllerModuleFileName, emitClientIndexModule, emitControllerModule, emitJobModule, emitJobsIndexModule, emitScriptsModule, jobModuleFileName, sortControllers, sortJobs, } from './emit.js';
+import { CLIENT_INDEX_FILE_NAME, JOBS_INDEX_FILE_NAME, controllerModuleFileName, emitClientIndexModule, emitControllerModule, emitJobModule, emitJobsIndexModule, findTypesReachedBy, emitScriptsModule, jobModuleFileName, sortControllers, sortJobs, } from './emit.js';
 import { jobDefinitionFileName, readJobContract, readJobFolderName } from './jobReader.js';
 import { toPosixPath } from './file-system.js';
 import { readInlinableTypesFile, selectInlinedTypes } from './typesFileReader.js';
@@ -175,12 +175,12 @@ export function planClientGeneration({ config, fileSystem }) {
     const jobsDirectory = resolve(config.jobs);
     const emittedJobs = [];
     /** Copies what one type import names into the job's sections, following imports between the files it reaches. */
-    function addInlinedTypes(sections, typeImport, fromLabel) {
+    function addInlinedTypes(sections, typeImport, fromLabel, sink) {
         const file = readInlinable(typeImport.specifier);
         if (!file || file === 'missing')
             return;
         const selected = selectInlinedTypes(file, typeImport.names, fromLabel, readInlinable);
-        problems.push(...selected.problems);
+        sink.push(...selected.problems);
         for (const selectedSection of selected.sections)
             addDeclarations(sections, selectedSection.filePath, selectedSection.declarations);
     }
@@ -224,13 +224,31 @@ export function planClientGeneration({ config, fileSystem }) {
         }
         const inlinedTypes = [];
         // What the job's own files declare, then whatever they take from a service: both are the run's shapes.
+        const inliningProblems = [];
         for (const folderFile of contract.folderFiles) {
             addDeclarations(inlinedTypes, folderFile.filePath, folderFile.declarations);
             for (const typeImport of folderFile.inlinedTypeImports)
-                addInlinedTypes(inlinedTypes, typeImport, folderFile.filePath);
+                addInlinedTypes(inlinedTypes, typeImport, folderFile.filePath, inliningProblems);
         }
         for (const typeImport of contract.inlinedTypeImports)
-            addInlinedTypes(inlinedTypes, typeImport, jobLabel);
+            addInlinedTypes(inlinedTypes, typeImport, jobLabel, inliningProblems);
+        // The result is the only shape of a run the client is given, so it is the only one that has to be
+        // carryable. A stage's working types stay on the server: the items a run is planned into may be built
+        // on a carrier's API request or a customer's configuration, and none of that is the client's business.
+        const carriedByResult = contract.resultType === undefined
+            ? new Set()
+            : findTypesReachedBy(contract.resultType, contract.typeDeclarations, inlinedTypes);
+        // One mistake, reported once: the message names the file the shape lives in, so which stage file
+        // imported it adds nothing, and a shape three stages name would otherwise be reported three times.
+        const reportedMessages = new Set();
+        for (const problem of inliningProblems) {
+            if (problem.about !== undefined && !carriedByResult.has(problem.about))
+                continue;
+            if (reportedMessages.has(problem.message))
+                continue;
+            reportedMessages.add(problem.message);
+            problems.push(problem);
+        }
         problems.push(...findDatesInJobInput(contract, inlinedTypes, jobLabel));
         emittedJobs.push({ contract, sourceLabel: jobLabel, inlinedTypes });
     }

package/dist-tooling/typesFileReader.js

@@ -92,6 +92,7 @@ export function selectInlinedTypes(file, names, controllerPath, resolveImport =
             else if (imported) {
                 problems.push({
                     filePath: controllerPath,
+                    about: dependent ?? name,
                     message: dependent
                         ? `type '${dependent}' (${current.filePath}) is built on ${name}, imported from '${importedFrom}' as a rename of ${exportedName}; import it under its own name so the client can carry it.`
                         : `type '${name}' is imported into ${current.filePath} from '${importedFrom}' as a rename of ${exportedName}; import it under its own name so the client can carry it.`,
@@ -100,6 +101,7 @@ export function selectInlinedTypes(file, names, controllerPath, resolveImport =
             else {
                 problems.push({
                     filePath: controllerPath,
+                    about: dependent ?? name,
                     message: dependent
                         ? `type '${dependent}' (${current.filePath}) is built on ${name} from '${importedFrom}', which the client cannot carry; write the wire shape out in the controller instead.`
                         : `type '${name}' is imported into ${current.filePath} from '${importedFrom}', not declared there; the client cannot carry it.`,
@@ -107,7 +109,7 @@ export function selectInlinedTypes(file, names, controllerPath, resolveImport =
             }
         }
         else if (dependent === undefined) {
-            problems.push({ filePath: controllerPath, message: `type '${name}' is not declared in ${current.filePath}.` });
+            problems.push({ filePath: controllerPath, about: name, message: `type '${name}' is not declared in ${current.filePath}.` });
         }
         // Anything else a declaration refers to is a global (Date, Record, Array): nothing to copy.
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amerilux/netsuite-api",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "private": false,
   "description": "The API layer for a NetSuite single-page app: endpoints served by a Restlet or a Suitelet, a typed browser client, SuiteScript module stubs for tests, and a generator that writes the client module from the controllers.",
   "license": "MIT",