@amerilux/netsuite-api 0.6.0 → 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';
@@ -242,7 +244,7 @@ export interface CloseStaleRequest { olderThanDays: number }
 export const getInputDataFunction = (input: CloseStaleRequest): StaleOrder[] => listStaleOrders(input.olderThanDays);
 ```
 
-A stage file exports the stage's name plus `Function`, because the definition file exports the plain names NetSuite looks for and the two would collide. A stage may also be written inline in the definition file, which suits a job whose stages are a line each — the cleanup job `npm run add:jobs` writes is one.
+A stage file exports the stage's name plus `Function`, because the definition file exports the plain names NetSuite looks for and the two would collide. A stage file may name a shape another file of the job's folder declares — the value a map stage writes is declared in map.ts and named again in summarize.ts — and the generator reads it there. A stage may also be written inline in the definition file, which suits a job whose stages are a line each — the cleanup job `npm run add:jobs` writes is one.
 
 The first parameter of `getInputData` is the run's input and the return type of `summarize` is its result: the generator reads the shapes from those two annotations wherever the stage is written, the way it reads an endpoint's request and response, and copies the shapes the result names into the browser's module whether the stage file declares them or takes them from a service. The values carried between stages are JSON, so each stage annotates what it expects (`values: number[]` on a reduce stage, `summary: JobSummary<Total>` on summarize) and the wrapper hands them back that way. Export the stages the job has, and `summarize` always: the run is closed there. A stage exported without being declared throws when NetSuite calls it, rather than quietly passing values through.
 

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);
     }
@@ -223,14 +223,32 @@ export function planClientGeneration({ config, fileSystem }) {
             problems.push({ filePath: jobLabel, message: `a controller is named '${contract.name}' too; their generated modules would be the same file.` });
         }
         const inlinedTypes = [];
-        // A stage file's own shapes, then whatever it takes from a service: both are the run's, written where its stages are.
-        for (const stageFile of contract.stageFiles) {
-            addDeclarations(inlinedTypes, stageFile.filePath, stageFile.declarations);
-            for (const typeImport of stageFile.inlinedTypeImports)
-                addInlinedTypes(inlinedTypes, typeImport, stageFile.filePath);
+        // 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, 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/jobReader.d.ts

@@ -32,10 +32,11 @@ export interface DeclaredJob {
     parameters: JobParameterContract[];
 }
 /**
- * A file a stage was read from: what it declares, and the type imports it carries. Its declarations are
- * copied into the browser's module like a service's, because a run's shapes are written where its stages are.
+ * A file of the job's own folder the reader had to read: a stage, or a file a stage takes a shape from. What
+ * it declares is copied into the browser's module like a service's, because a run's shapes are written where
+ * its stages are — the value a map stage writes is declared in map.ts and named again in summarize.ts.
  */
-export interface JobStageFile {
+export interface JobFolderFile {
     filePath: string;
     declarations: TypeDeclaration[];
     inlinedTypeImports: InlinedTypeImport[];
@@ -68,8 +69,8 @@ export interface JobContract {
     stages: JobStageName[];
     /** The stages the file exports as NetSuite entry points. */
     exportedStages: string[];
-    /** The files the stages were imported from, in the order they were read. */
-    stageFiles: JobStageFile[];
+    /** The files of the job's folder that were read, in that order: its stages, and whatever they name. */
+    folderFiles: JobFolderFile[];
 }
 export interface JobReadResult {
     contract?: JobContract;

package/dist-tooling/jobReader.js

@@ -133,7 +133,7 @@ function readJobDeclaration(declaration, jobName, filePath) {
  * The exported type declarations of a file and the type imports it carries, for a job's definition file
  * or for one of its stage files: both end up in the browser's module, so both are read the same way.
  */
-function readFileTypes(sourceFile, filePath, options) {
+function readFileTypes(sourceFile, filePath, options, folderFiles) {
     const declarations = [];
     const carriedTypeImports = [];
     const inlinedTypeImports = [];
@@ -141,7 +141,6 @@ function readFileTypes(sourceFile, filePath, options) {
     for (const statement of sourceFile.statements) {
         if (ts.isImportDeclaration(statement)) {
             const result = readTypeImport(statement, filePath, options);
-            problems.push(...result.problems);
             if (result.read?.kind === 'carried')
                 carriedTypeImports.push(result.read.typeImport);
             else if (result.read?.kind === 'inlined')
@@ -149,6 +148,14 @@ function readFileTypes(sourceFile, filePath, options) {
             else if (result.read?.kind === 'controller') {
                 problems.push({ filePath, message: "a job does not take types from a controller; its input and result are its own, or a service's." });
             }
+            else if (result.problems.length > 0 && ts.isStringLiteral(statement.moduleSpecifier) && isRelativeSpecifier(statement.moduleSpecifier.text)) {
+                // A shape another file of this job's folder declares: read there instead of reported as unreachable.
+                const sibling = folderFiles?.read(statement.moduleSpecifier.text);
+                if (!sibling)
+                    problems.push(...result.problems);
+                continue;
+            }
+            problems.push(...result.problems);
             continue;
         }
         if (!ts.isInterfaceDeclaration(statement) && !ts.isTypeAliasDeclaration(statement) && !ts.isEnumDeclaration(statement))
@@ -166,6 +173,35 @@ function readFileTypes(sourceFile, filePath, options) {
     }
     return { declarations, carriedTypeImports, inlinedTypeImports, problems };
 }
+function isRelativeSpecifier(specifier) {
+    return specifier.startsWith('./') || specifier.startsWith('../');
+}
+function createJobFolderFiles(options) {
+    const collected = [];
+    const problems = [];
+    const bySpecifier = new Map();
+    const folderFiles = {
+        collected,
+        problems,
+        read(specifier) {
+            if (bySpecifier.has(specifier))
+                return bySpecifier.get(specifier);
+            const read = options.readStageFile?.(specifier);
+            if (!read) {
+                bySpecifier.set(specifier, undefined);
+                return undefined;
+            }
+            const sourceFile = ts.createSourceFile(read.filePath, read.source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+            const entry = { sourceFile, filePath: read.filePath };
+            bySpecifier.set(specifier, entry);
+            const types = readFileTypes(sourceFile, read.filePath, options, folderFiles);
+            problems.push(...types.problems);
+            collected.push({ filePath: read.filePath, declarations: types.declarations, inlinedTypeImports: types.inlinedTypeImports, carriedTypeImports: types.carriedTypeImports });
+            return entry;
+        },
+    };
+    return folderFiles;
+}
 /** `import { mapFunction } from './map'`: every value imported by name, by the name this file calls it. */
 function readValueImports(sourceFile) {
     const valueImports = new Map();
@@ -200,30 +236,12 @@ function findExportedFunction(sourceFile, name) {
     }
     return undefined;
 }
-function readStages(literal, filePath, sourceFile, options) {
+function readStages(literal, filePath, sourceFile, folderFiles) {
     const problems = [];
     const stages = [];
-    const stageFiles = [];
     const valueImports = readValueImports(sourceFile);
-    const filesBySpecifier = new Map();
     let inputType;
     let resultType;
-    /** A stage file, read once however many stages come from it, and its shapes collected as it is read. */
-    function readStageFile(specifier) {
-        const alreadyRead = filesBySpecifier.get(specifier);
-        if (alreadyRead)
-            return alreadyRead;
-        const read = options.readStageFile?.(specifier);
-        if (!read)
-            return undefined;
-        const stageSourceFile = ts.createSourceFile(read.filePath, read.source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
-        const types = readFileTypes(stageSourceFile, read.filePath, options);
-        problems.push(...types.problems);
-        stageFiles.push({ filePath: read.filePath, declarations: types.declarations, inlinedTypeImports: types.inlinedTypeImports, carriedTypeImports: types.carriedTypeImports });
-        const entry = { sourceFile: stageSourceFile, filePath: read.filePath };
-        filesBySpecifier.set(specifier, entry);
-        return entry;
-    }
     /** The function a stage names, in the file it is imported from: `getInputData: getInputDataFunction`. */
     function findReferencedStage(stageName, referenced) {
         const imported = valueImports.get(referenced);
@@ -235,7 +253,7 @@ function readStages(literal, filePath, sourceFile, options) {
             problems.push({ filePath, message: `stage '${stageName}' comes from '${imported.specifier}'; a stage is imported from a file beside the job, such as './${stageName}'.` });
             return undefined;
         }
-        const stageFile = readStageFile(imported.specifier);
+        const stageFile = folderFiles.read(imported.specifier);
         if (!stageFile) {
             problems.push({ filePath, message: `stage '${stageName}' is imported from '${imported.specifier}', which is not a file beside the job the generator can read.` });
             return undefined;
@@ -295,7 +313,7 @@ function readStages(literal, filePath, sourceFile, options) {
     if (!stages.includes('map') && !stages.includes('reduce')) {
         problems.push({ filePath, message: 'a job declares a map stage, a reduce stage, or both; NetSuite has nothing to run otherwise.' });
     }
-    return { stages, inputType, resultType, stageFiles, problems };
+    return { stages, inputType, resultType, problems };
 }
 export function readJobContract(filePath, source, options) {
     const problems = [];
@@ -314,7 +332,8 @@ export function readJobContract(filePath, source, options) {
     if (header !== JOB_SCRIPT_TYPE_HEADER) {
         problems.push({ filePath, message: `the leading JSDoc says '@NScriptType ${header ?? '(none)'}'; a job is a ${JOB_SCRIPT_TYPE_HEADER}.` });
     }
-    const fileTypes = readFileTypes(sourceFile, filePath, options);
+    const folderFiles = createJobFolderFiles(options);
+    const fileTypes = readFileTypes(sourceFile, filePath, options, folderFiles);
     problems.push(...fileTypes.problems);
     const { carriedTypeImports, inlinedTypeImports, declarations: typeDeclarations } = fileTypes;
     let contract;
@@ -342,7 +361,7 @@ export function readJobContract(filePath, source, options) {
         }
         const declared = readJobDeclaration(declarationArgument, name, filePath);
         problems.push(...declared.problems);
-        const stages = readStages(stagesArgument, filePath, sourceFile, options);
+        const stages = readStages(stagesArgument, filePath, sourceFile, folderFiles);
         problems.push(...stages.problems);
         for (const exported of found.exportedStages) {
             if (!JOB_STAGE_NAMES.includes(exported)) {
@@ -371,9 +390,10 @@ export function readJobContract(filePath, source, options) {
             resultType: stages.resultType,
             stages: stages.stages,
             exportedStages: found.exportedStages,
-            stageFiles: stages.stageFiles,
+            folderFiles: folderFiles.collected,
         };
     }
+    problems.push(...folderFiles.problems);
     if (!contract) {
         if (problems.length === 0) {
             problems.push({ filePath, message: 'must declare its script: `export const { getInputData, map, summarize } = defineJob({ name, scriptId, deployments, runParameter, runs }, { ... })`.' });

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.0",
+  "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",