@amerilux/netsuite-api 0.6.0 → 0.6.1

package/README.md

@@ -242,7 +242,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/generate.js

@@ -223,11 +223,11 @@ 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.
+        for (const folderFile of contract.folderFiles) {
+            addDeclarations(inlinedTypes, folderFile.filePath, folderFile.declarations);
+            for (const typeImport of folderFile.inlinedTypeImports)
+                addInlinedTypes(inlinedTypes, typeImport, folderFile.filePath);
         }
         for (const typeImport of contract.inlinedTypeImports)
             addInlinedTypes(inlinedTypes, typeImport, jobLabel);

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amerilux/netsuite-api",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "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",