@amerilux/netsuite-api 0.5.0 → 0.6.1

package/README.md

@@ -121,11 +121,16 @@ A hook imports `{ customer }` from it, calls `customer.api.search({ search: 'acm
   "clientModule": "@amerilux/netsuite-api/client",
   "wireModule": "@amerilux/netsuite-api",
   "typeImports": { "@amerilux/netsuite-api/server": "@amerilux/netsuite-api/client" },
-  "inlineTypes": { "../types/models.gen": "api/src/types/models.gen.ts", "../services/*": "api/src/services/*.ts" }
+  "inlineTypes": {
+    "../types/models.gen": "api/src/types/models.gen.ts",
+    "../services/*": "api/src/services/*.ts",
+    "../../types/models.gen": "api/src/types/models.gen.ts",
+    "../../services/*": "api/src/services/*.ts"
+  }
 }
 ```
 
-Paths are relative to the config file. `outDir` holds the controller and job modules and their indexes, and nothing else. A project with jobs adds a `jobRuns` block naming the run record it deployed; see **Jobs**. `inlineTypes` maps a specifier as written in a controller to the file whose type declarations are copied into the module of every controller importing from it; a key with one `*` stands for a file name and the `*` in its file takes that name, so `../services/*` covers every service. Only the type declarations of a file are read, so a service's functions are skipped; a type in one inlined file that refers to a type imported from another (a service's summary type built on an entity type) brings that type along, the import resolved through the same map as written from the same folder depth. `typeImports` maps a specifier to the one the client resolves, for a type that stays an import (the package's server entry maps to its client entry so `RawResponse` carries over). A type imported from any other module is an error.
+Paths are relative to the config file. `outDir` holds the controller and job modules and their indexes, and nothing else. A project with jobs adds a `jobRuns` block naming the run record it deployed; see **Jobs**. `inlineTypes` maps a specifier as written in a controller to the file whose type declarations are copied into the module of every controller importing from it; a key with one `*` stands for a file name and the `*` in its file takes that name, so `../services/*` covers every service. Only the type declarations of a file are read, so a service's functions are skipped; a type in one inlined file that refers to a type imported from another (a service's summary type built on an entity type) brings that type along, the import resolved through the same map as written from the same folder depth. The `../../` entries are the same two files named from one folder deeper, because a job is a folder and its stage files sit inside it. `typeImports` maps a specifier to the one the client resolves, for a type that stays an import (the package's server entry maps to its client entry so `RawResponse` carries over). A type imported from any other module is an error.
 
 ## The client at runtime
 
@@ -195,19 +200,21 @@ export const listRolesForEmployee = (employeeId: number) => userRolesApi.byEmplo
 
 ## Jobs
 
-A job is a Map/Reduce script written as stages. What the wrapper adds is the run: a Map/Reduce answers nothing and cannot be waited on, so every run is a row in a record of the application's own, and that row is what server code and the browser talk about.
+A job is a Map/Reduce script written as stages, and it is a folder: `api/src/jobs/<name>/<name>.ts` declares it and the stages it is made of sit beside it, one file each. What the wrapper adds is the run: a Map/Reduce answers nothing and cannot be waited on, so every run is a row in a record of the application's own, and that row is what server code and the browser talk about.
+
+The definition file is a declaration and a wiring, so what a job is reads at a glance: its ids, its deployments, its parameters, and which stages it has.
 
 ```ts
+// api/src/jobs/closeStaleOrders/closeStaleOrders.ts
 /**
  * @NApiVersion 2.1
  * @NScriptType MapReduceScript
  */
 import { defineJob } from '@amerilux/netsuite-api/server';
-import { jobRuns } from '../scripts.gen';
-import { closeOrder, listStaleOrders, type StaleOrder } from '../services/staleOrderService';
-
-export interface CloseStaleRequest { olderThanDays: number }
-export interface CloseStaleResult { closed: number }
+import { jobRuns } from '../../scripts.gen';
+import { getInputDataFunction } from './getInputData';
+import { mapFunction } from './map';
+import { summarizeFunction } from './summarize';
 
 export const { getInputData, map, summarize } = defineJob({
     name: 'closeStaleOrders',
@@ -217,21 +224,33 @@ export const { getInputData, map, summarize } = defineJob({
     parameters: { batchSize: { id: 'custscript_app_close_stale_batch', type: 'integer' } },
     runs: jobRuns,
 }, {
-    getInputData: (input: CloseStaleRequest): StaleOrder[] => listStaleOrders(input.olderThanDays),
-    map: (order: StaleOrder, job): void => {
-        if (closeOrder(order.id)) job.write(String(order.id), order.id);
-    },
-    summarize: (summary): CloseStaleResult => ({ closed: summary.output.length }),
+    getInputData: getInputDataFunction,
+    map: mapFunction,
+    summarize: summarizeFunction,
 });
 ```
 
-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, the way it reads an endpoint's request and response. 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.
+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:
+
+```ts
+// api/src/jobs/closeStaleOrders/getInputData.ts
+import { listStaleOrders, type StaleOrder } from '../../services/staleOrderService';
+
+/** What a run of this job is asked to do. */
+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 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.
 
 Plenty of jobs answer nothing, because the records they write are the point. Such a job declares no `summarize` and still exports it, and the wrapper closes the run for it; one that wants a last word without a result (a notification when the run ends) declares `summarize` with a `void` return. Either way the run's `Result` is `null`, and a page watches `status`, the progress fields and `errors` instead of a result.
 
 Reading a run asks the task about progress as well. `stagePercentComplete` is `getPercentageCompleted()`, which NetSuite documents as the percentage complete of the **stage being processed**, so it counts to 100 once per stage; `itemsProcessed` and `itemsTotal` come from that stage's `getTotal*Count()` and `getPending*Count()` pair and only go up. The record keeps the percent (100 once a run ends) but never the counts, so the counts are null for a run that has ended or whose task id NetSuite has purged — by then the run has the result, which the record did keep.
 
-The store belongs in a repository, because it writes a record and submits a task. Keep it job-agnostic: whatever decides a run should start (a service, in the layout the template scaffolds) passes the job and the input.
+The store belongs in a repository, because it writes a record and submits a task. Keep it job-agnostic: whatever decides a run should start passes the job and the input. In the folder shape that decision belongs in the job's own folder (`start.ts`), so everything about a job is one place and a controller reaches for it by name.
 
 ```ts
 // api/src/repositories/jobRunRepository.ts

package/dist-tooling/config.js

@@ -27,7 +27,13 @@ export const defaultClientGeneratorConfig = {
     clientModule: '@amerilux/netsuite-api/client',
     wireModule: '@amerilux/netsuite-api',
     typeImports: { '@amerilux/netsuite-api/server': '@amerilux/netsuite-api/client' },
-    inlineTypes: { '../types/models.gen': 'api/src/types/models.gen.ts', '../services/*': 'api/src/services/*.ts' },
+    inlineTypes: {
+        '../types/models.gen': 'api/src/types/models.gen.ts',
+        '../services/*': 'api/src/services/*.ts',
+        // A job is a folder, so its definition and its stage files name the same places from one level deeper.
+        '../../types/models.gen': 'api/src/types/models.gen.ts',
+        '../../services/*': 'api/src/services/*.ts',
+    },
 };
 const wildcardInlineTypesKeyPattern = /^([^*]*)\*([^*]*)$/;
 const wildcardSegmentPattern = /^[A-Za-z0-9_-]+$/;

package/dist-tooling/file-system.d.ts

@@ -8,6 +8,8 @@ export interface FileSystemAdapter {
     ensureDirectory(directoryPath: string): void;
     /** Lists the absolute paths of the files directly inside a directory. Returns [] when it does not exist. */
     listFiles(directoryPath: string): string[];
+    /** Lists the absolute paths of the directories directly inside a directory: one per job, under the jobs folder. */
+    listDirectories(directoryPath: string): string[];
 }
 export declare function toPosixPath(filePath: string): string;
 export declare function createNodeFileSystemAdapter(): FileSystemAdapter;

package/dist-tooling/file-system.js

@@ -19,6 +19,15 @@ export function createNodeFileSystemAdapter() {
                 .map((entry) => nodePath.join(directoryPath, entry.name))
                 .sort();
         },
+        listDirectories: (directoryPath) => {
+            if (!nodeFileSystem.existsSync(directoryPath) || !nodeFileSystem.statSync(directoryPath).isDirectory())
+                return [];
+            return nodeFileSystem
+                .readdirSync(directoryPath, { withFileTypes: true })
+                .filter((entry) => entry.isDirectory())
+                .map((entry) => nodePath.join(directoryPath, entry.name))
+                .sort();
+        },
     };
 }
 function normalizeKey(filePath) {
@@ -53,5 +62,19 @@ export function createInMemoryFileSystemAdapter(initialFiles = {}) {
                 .filter((filePath) => filePath.startsWith(prefix) && !filePath.slice(prefix.length).includes('/'))
                 .sort();
         },
+        listDirectories: (directoryPath) => {
+            const prefix = `${normalizeKey(directoryPath)}/`;
+            const names = new Set();
+            for (const filePath of [...files.keys(), ...directories]) {
+                if (!filePath.startsWith(prefix))
+                    continue;
+                const [name, ...rest] = filePath.slice(prefix.length).split('/');
+                if (name !== undefined && rest.length > 0)
+                    names.add(name);
+            }
+            return Array.from(names)
+                .sort()
+                .map((name) => `${prefix}${name}`);
+        },
     };
 }

package/dist-tooling/generate.js

@@ -2,7 +2,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 { isJobFileName, readJobContract } from './jobReader.js';
+import { jobDefinitionFileName, readJobContract, readJobFolderName } from './jobReader.js';
 import { toPosixPath } from './file-system.js';
 import { readInlinableTypesFile, selectInlinedTypes } from './typesFileReader.js';
 import { readReferencedNames } from './wireTypes.js';
@@ -169,16 +169,52 @@ export function planClientGeneration({ config, fileSystem }) {
         problems.push(...findDatesInRequestShapes(contract, inlinedTypes, controllerLabel));
         emitted.push({ contract, sourceLabel: controllerLabel, inlinedTypes });
     }
-    // Jobs: the same reading, with a run instead of a request and a record instead of a reply.
+    // Jobs: the same reading, with a run instead of a request and a record instead of a reply. A job is a
+    // folder — <name>/<name>.ts declares it and its stage files sit beside it — so the shapes on either end
+    // of a run are read wherever the stage that names them lives.
     const jobsDirectory = resolve(config.jobs);
     const emittedJobs = [];
-    for (const filePath of fileSystem.listFiles(jobsDirectory)) {
-        const jobLabel = label(filePath);
-        if (!isJobFileName(nodePath.basename(filePath))) {
-            problems.push({ filePath: jobLabel, message: 'a job file is named <name>.ts, with <name> in camelCase; nothing else lives in the jobs folder.' });
+    /** Copies what one type import names into the job's sections, following imports between the files it reaches. */
+    function addInlinedTypes(sections, typeImport, fromLabel) {
+        const file = readInlinable(typeImport.specifier);
+        if (!file || file === 'missing')
+            return;
+        const selected = selectInlinedTypes(file, typeImport.names, fromLabel, readInlinable);
+        problems.push(...selected.problems);
+        for (const selectedSection of selected.sections)
+            addDeclarations(sections, selectedSection.filePath, selectedSection.declarations);
+    }
+    /** One section per source file, so a shape copied twice is written once. */
+    function addDeclarations(sections, sourceLabel, declarations) {
+        const section = sections.find((existing) => existing.sourceLabel === sourceLabel);
+        if (section)
+            section.declarations.push(...declarations.filter((declaration) => !section.declarations.some((existing) => existing.name === declaration.name)));
+        else
+            sections.push({ sourceLabel, declarations: [...declarations] });
+    }
+    for (const strayPath of fileSystem.listFiles(jobsDirectory)) {
+        problems.push({ filePath: label(strayPath), message: 'a job lives in a folder of its own, declared by the file of that name; nothing sits in the jobs folder itself.' });
+    }
+    for (const jobDirectory of fileSystem.listDirectories(jobsDirectory)) {
+        const jobName = readJobFolderName(nodePath.basename(jobDirectory));
+        if (jobName === undefined) {
+            problems.push({ filePath: label(jobDirectory), message: 'a job folder is named for its job, in camelCase.' });
+            continue;
+        }
+        const definitionPath = nodePath.join(jobDirectory, jobDefinitionFileName(jobName));
+        if (!fileSystem.fileExists(definitionPath)) {
+            problems.push({ filePath: label(jobDirectory), message: `there is no ${jobDefinitionFileName(jobName)} here; the file of the folder's own name is what declares the job.` });
             continue;
         }
-        const result = readJobContract(jobLabel, fileSystem.readTextFile(filePath), { typeImports: config.typeImports, inlineTypes: config.inlineTypes });
+        const jobLabel = label(definitionPath);
+        const result = readJobContract(jobLabel, fileSystem.readTextFile(definitionPath), {
+            typeImports: config.typeImports,
+            inlineTypes: config.inlineTypes,
+            readStageFile: (specifier) => {
+                const stagePath = `${nodePath.resolve(jobDirectory, specifier)}.ts`;
+                return fileSystem.fileExists(stagePath) ? { filePath: label(stagePath), source: fileSystem.readTextFile(stagePath) } : undefined;
+            },
+        });
         problems.push(...result.problems);
         const contract = result.contract;
         if (!contract)
@@ -187,20 +223,14 @@ 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 = [];
-        for (const typeImport of contract.inlinedTypeImports) {
-            const file = readInlinable(typeImport.specifier);
-            if (!file || file === 'missing')
-                continue;
-            const selected = selectInlinedTypes(file, typeImport.names, jobLabel, readInlinable);
-            problems.push(...selected.problems);
-            for (const selectedSection of selected.sections) {
-                const section = inlinedTypes.find((existing) => existing.sourceLabel === selectedSection.filePath);
-                if (section)
-                    section.declarations.push(...selectedSection.declarations.filter((declaration) => !section.declarations.some((existing) => existing.name === declaration.name)));
-                else
-                    inlinedTypes.push({ sourceLabel: selectedSection.filePath, declarations: selectedSection.declarations });
-            }
+        // 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);
         problems.push(...findDatesInJobInput(contract, inlinedTypes, jobLabel));
         emittedJobs.push({ contract, sourceLabel: jobLabel, inlinedTypes });
     }

package/dist-tooling/index.d.ts

@@ -4,7 +4,7 @@ export { JOB_RUN_FIELD_SUFFIXES, netsuiteValueTypeNames, resolveJobRunFieldIds }
 export type { ClientGeneratorConfig, JobRunFieldName, JobRunsSettings, NetsuiteValueTypeName, ResolvedClientGeneratorConfig } from './config.js';
 export { GENERATED_CLIENT_NAME, GENERATED_ENDPOINTS_TYPE_NAME, RAW_RESPONSE_TYPE_NAME, isControllerFileName, readControllerContract, readLeadingJsDoc } from './controllerReader.js';
 export type { CarriedTypeImport, ControllerContract, ControllerKind, ControllerProblem, ControllerReadResult, ControllerTypeImport, DeclaredScript, EndpointSignature, InlinedTypeImport, ReadControllerOptions, TypeDeclaration, TypeImportName } from './controllerReader.js';
-export { GENERATED_JOB_RESULT_TYPE_NAME, JOB_SCRIPT_TYPE_HEADER, JOB_STAGE_NAMES, isJobFileName, readJobContract } from './jobReader.js';
+export { GENERATED_JOB_RESULT_TYPE_NAME, JOB_SCRIPT_TYPE_HEADER, JOB_STAGE_NAMES, jobDefinitionFileName, readJobContract, readJobFolderName } from './jobReader.js';
 export type { DeclaredJob, JobContract, JobParameterContract, JobReadResult, JobStageName } from './jobReader.js';
 export { readInlinableTypesFile, selectInlinedTypes } from './typesFileReader.js';
 export type { InlinableTypeDeclaration, InlinableTypesFile, SelectedInlinedTypes } from './typesFileReader.js';

package/dist-tooling/index.js

@@ -2,7 +2,7 @@
 export { DEFAULT_CONFIG_FILE_NAME, ClientGeneratorConfigError, defaultClientGeneratorConfig, loadClientGeneratorConfig } from './config.js';
 export { JOB_RUN_FIELD_SUFFIXES, netsuiteValueTypeNames, resolveJobRunFieldIds } from './config.js';
 export { GENERATED_CLIENT_NAME, GENERATED_ENDPOINTS_TYPE_NAME, RAW_RESPONSE_TYPE_NAME, isControllerFileName, readControllerContract, readLeadingJsDoc } from './controllerReader.js';
-export { GENERATED_JOB_RESULT_TYPE_NAME, JOB_SCRIPT_TYPE_HEADER, JOB_STAGE_NAMES, isJobFileName, readJobContract } from './jobReader.js';
+export { GENERATED_JOB_RESULT_TYPE_NAME, JOB_SCRIPT_TYPE_HEADER, JOB_STAGE_NAMES, jobDefinitionFileName, readJobContract, readJobFolderName } from './jobReader.js';
 export { readInlinableTypesFile, selectInlinedTypes } from './typesFileReader.js';
 export { CLIENT_INDEX_FILE_NAME, JOBS_INDEX_FILE_NAME, controllerModuleFileName, emitClientIndexModule, emitControllerModule, emitJobModule, emitJobsIndexModule, emitScriptsModule, jobModuleFileName } from './emit.js';
 export { checkClientGeneration, planClientGeneration, runClientGeneration } from './generate.js';

package/dist-tooling/jobReader.d.ts

@@ -1,10 +1,14 @@
 import type { CarriedTypeImport, ControllerProblem, InlinedTypeImport, ReadControllerOptions, TypeDeclaration } from './controllerReader.js';
 /**
- * Reads what a job run carries, from its source alone: the script it declares in its defineJob call,
- * the stages it has, and the types on either end of a run. A run's input is the first parameter of
- * getInputData and its result is what summarize returns, so those two annotations are the contract,
- * the way a handler's parameter and return type are a controller's. A parse, not a type check: the
- * ids are string literals and the shapes are written out.
+ * Reads what a job run carries: the script it declares in its defineJob call, the stages it has, and
+ * the types on either end of a run. A run's input is the first parameter of getInputData and its result
+ * is what summarize returns, so those two annotations are the contract, the way a handler's parameter
+ * and return type are a controller's. A parse, not a type check: the ids are string literals and the
+ * shapes are written out.
+ *
+ * A job is a folder — `<name>/<name>.ts` declares it — and a stage is either a function written inline
+ * or one imported from a file beside it (`./map`), which is where the annotations are then read from. So
+ * a developer opens map.ts to see what the map stage does, and the definition file stays a declaration.
  */
 /** The stage names a job may declare, in the order NetSuite calls them. */
 export declare const JOB_STAGE_NAMES: readonly ["getInputData", "map", "reduce", "summarize"];
@@ -27,6 +31,28 @@ export interface DeclaredJob {
     runParameter: string;
     parameters: JobParameterContract[];
 }
+/**
+ * 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 JobFolderFile {
+    filePath: string;
+    declarations: TypeDeclaration[];
+    inlinedTypeImports: InlinedTypeImport[];
+    carriedTypeImports: CarriedTypeImport[];
+}
+/** What a job's reader needs beyond a controller's: the files its stages are imported from. */
+export interface ReadJobOptions extends ReadControllerOptions {
+    /**
+     * Reads a file a stage is imported from, the specifier resolved against the job's own folder, or
+     * undefined when there is no such file. Without it, only inline stages can be read.
+     */
+    readStageFile?(specifier: string): {
+        filePath: string;
+        source: string;
+    } | undefined;
+}
 export interface JobContract {
     /** The job's name: `closeStaleOrders` for closeStaleOrders.ts, matching `name` in its declaration. */
     name: string;
@@ -43,11 +69,16 @@ export interface JobContract {
     stages: JobStageName[];
     /** The stages the file exports as NetSuite entry points. */
     exportedStages: string[];
+    /** 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;
     problems: ControllerProblem[];
 }
-export declare function isJobFileName(fileName: string): boolean;
-export declare function readJobContract(filePath: string, source: string, options: ReadControllerOptions): JobReadResult;
+/** The name a job folder declares: `approveOrders` for api/src/jobs/approveOrders, or undefined when it is not a name. */
+export declare function readJobFolderName(folderName: string): string | undefined;
+/** The file that declares the job of a folder: the folder's own name again, so the file is unique to open and to search for. */
+export declare function jobDefinitionFileName(jobName: string): string;
+export declare function readJobContract(filePath: string, source: string, options: ReadJobOptions): JobReadResult;
 export {};

package/dist-tooling/jobReader.js

@@ -3,11 +3,15 @@ import ts from 'typescript';
 import { hasExportModifier, readLeadingJsDoc, readScriptTypeHeader, readStringProperty, readTypeImport } from './controllerReader.js';
 import { toPosixPath } from './file-system.js';
 /**
- * Reads what a job run carries, from its source alone: the script it declares in its defineJob call,
- * the stages it has, and the types on either end of a run. A run's input is the first parameter of
- * getInputData and its result is what summarize returns, so those two annotations are the contract,
- * the way a handler's parameter and return type are a controller's. A parse, not a type check: the
- * ids are string literals and the shapes are written out.
+ * Reads what a job run carries: the script it declares in its defineJob call, the stages it has, and
+ * the types on either end of a run. A run's input is the first parameter of getInputData and its result
+ * is what summarize returns, so those two annotations are the contract, the way a handler's parameter
+ * and return type are a controller's. A parse, not a type check: the ids are string literals and the
+ * shapes are written out.
+ *
+ * A job is a folder — `<name>/<name>.ts` declares it — and a stage is either a function written inline
+ * or one imported from a file beside it (`./map`), which is where the annotations are then read from. So
+ * a developer opens map.ts to see what the map stage does, and the definition file stays a declaration.
  */
 /** The stage names a job may declare, in the order NetSuite calls them. */
 export const JOB_STAGE_NAMES = ['getInputData', 'map', 'reduce', 'summarize'];
@@ -16,9 +20,15 @@ export const JOB_SCRIPT_TYPE_HEADER = 'MapReduceScript';
 /** The type the generated job module gives the run's input, and the one it gives the result. */
 export const GENERATED_JOB_RESULT_TYPE_NAME = 'Result';
 const jobFileNamePattern = /^([a-z][A-Za-z0-9]*)\.ts$/;
+const jobFolderNamePattern = /^[a-z][A-Za-z0-9]*$/;
 const netsuiteValueTypes = ['text', 'integer', 'decimal', 'checkbox', 'date', 'select'];
-export function isJobFileName(fileName) {
-    return jobFileNamePattern.test(fileName) && !fileName.endsWith('.d.ts');
+/** The name a job folder declares: `approveOrders` for api/src/jobs/approveOrders, or undefined when it is not a name. */
+export function readJobFolderName(folderName) {
+    return jobFolderNamePattern.test(folderName) ? folderName : undefined;
+}
+/** The file that declares the job of a folder: the folder's own name again, so the file is unique to open and to search for. */
+export function jobDefinitionFileName(jobName) {
+    return `${jobName}.ts`;
 }
 /** `export const { getInputData, map, summarize } = defineJob(...)`: the call, and the names it exports. */
 function findDefineJobCall(statement) {
@@ -98,7 +108,7 @@ function readJobDeclaration(declaration, jobName, filePath) {
     if (name === undefined)
         problems.push({ filePath, message: "the job declaration needs 'name' as a string literal; the generator reads it from the source." });
     else if (name !== jobName)
-        problems.push({ filePath, message: `the job declaration says name: '${name}' but the file is ${jobName}.ts; the name is the file name.` });
+        problems.push({ filePath, message: `the job declaration says name: '${name}' but the job is ${jobName}; the name is the job's folder and file name.` });
     if (scriptId === undefined)
         problems.push({ filePath, message: "the job declaration needs 'scriptId' as a string literal." });
     if (runParameter === undefined) {
@@ -119,38 +129,183 @@ function readJobDeclaration(declaration, jobName, filePath) {
         return { problems };
     return { script: { scriptId, deployments, runParameter, parameters: readParametersResult.parameters }, problems };
 }
-function readStages(literal, filePath, sourceFile) {
+/**
+ * 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, folderFiles) {
+    const declarations = [];
+    const carriedTypeImports = [];
+    const inlinedTypeImports = [];
+    const problems = [];
+    for (const statement of sourceFile.statements) {
+        if (ts.isImportDeclaration(statement)) {
+            const result = readTypeImport(statement, filePath, options);
+            if (result.read?.kind === 'carried')
+                carriedTypeImports.push(result.read.typeImport);
+            else if (result.read?.kind === 'inlined')
+                inlinedTypeImports.push(result.read.typeImport);
+            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))
+            continue;
+        if (!hasExportModifier(statement)) {
+            problems.push({ filePath, message: `'${statement.name.text}' is not exported; the generator copies the shapes a run's result names into the browser's module as they are written, so export them.` });
+            continue;
+        }
+        if (statement.name.text === GENERATED_JOB_RESULT_TYPE_NAME) {
+            problems.push({ filePath, message: `type '${statement.name.text}' is the name the generated module gives the run's result; call this shape something else.` });
+            continue;
+        }
+        const jsDoc = readLeadingJsDoc(statement, sourceFile);
+        declarations.push({ name: statement.name.text, text: `${jsDoc ? `${jsDoc}\n` : ''}${statement.getText(sourceFile)}` });
+    }
+    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();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier))
+            continue;
+        const clause = statement.importClause;
+        if (!clause || clause.isTypeOnly || !clause.namedBindings || !ts.isNamedImports(clause.namedBindings))
+            continue;
+        for (const element of clause.namedBindings.elements) {
+            if (element.isTypeOnly)
+                continue;
+            valueImports.set(element.name.text, { specifier: statement.moduleSpecifier.text, importedName: (element.propertyName ?? element.name).text });
+        }
+    }
+    return valueImports;
+}
+/** The exported function of that name in a stage file: `export const mapFunction = …` or `export function mapFunction…`. */
+function findExportedFunction(sourceFile, name) {
+    for (const statement of sourceFile.statements) {
+        if (ts.isFunctionDeclaration(statement) && hasExportModifier(statement) && statement.name?.text === name)
+            return statement;
+        if (!ts.isVariableStatement(statement) || !hasExportModifier(statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(declaration.name) || declaration.name.text !== name)
+                continue;
+            const initializer = declaration.initializer;
+            if (initializer && (ts.isArrowFunction(initializer) || ts.isFunctionExpression(initializer)))
+                return initializer;
+        }
+    }
+    return undefined;
+}
+function readStages(literal, filePath, sourceFile, folderFiles) {
     const problems = [];
     const stages = [];
+    const valueImports = readValueImports(sourceFile);
     let inputType;
     let resultType;
+    /** The function a stage names, in the file it is imported from: `getInputData: getInputDataFunction`. */
+    function findReferencedStage(stageName, referenced) {
+        const imported = valueImports.get(referenced);
+        if (!imported) {
+            problems.push({ filePath, message: `stage '${stageName}' names '${referenced}', which this file does not import; a stage is written inline or imported from a file beside the job.` });
+            return undefined;
+        }
+        if (!imported.specifier.startsWith('./') && !imported.specifier.startsWith('../')) {
+            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 = 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;
+        }
+        const handler = findExportedFunction(stageFile.sourceFile, imported.importedName);
+        if (!handler) {
+            problems.push({ filePath: stageFile.filePath, message: `'${imported.importedName}' is not exported from here as a function, and stage '${stageName}' names it; its annotations are the run's contract.` });
+            return undefined;
+        }
+        return { handler, sourceFile: stageFile.sourceFile, filePath: stageFile.filePath };
+    }
     for (const property of literal.properties) {
         const stageName = property.name && (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) ? property.name.text : undefined;
         if (stageName === undefined || !JOB_STAGE_NAMES.includes(stageName)) {
             problems.push({ filePath, message: `'${stageName ?? 'a stage'}' is not a stage; a job declares ${JOB_STAGE_NAMES.join(', ')}.` });
             continue;
         }
+        // Where the annotations are read from: the definition file for an inline stage, the stage's own file otherwise.
         let handler;
+        let annotatedIn = { sourceFile, filePath };
         if (ts.isMethodDeclaration(property))
             handler = property;
         else if (ts.isPropertyAssignment(property) && (ts.isArrowFunction(property.initializer) || ts.isFunctionExpression(property.initializer)))
             handler = property.initializer;
-        if (!handler) {
-            problems.push({ filePath, message: `stage '${stageName}' must be an inline function; a reference to a function elsewhere carries no types the generator can read.` });
-            continue;
+        else {
+            const referenced = ts.isShorthandPropertyAssignment(property)
+                ? property.name.text
+                : ts.isPropertyAssignment(property) && ts.isIdentifier(property.initializer)
+                    ? property.initializer.text
+                    : undefined;
+            if (referenced === undefined) {
+                problems.push({ filePath, message: `stage '${stageName}' is neither a function nor the name of one; write it inline or import it from a file beside the job.` });
+                continue;
+            }
+            const found = findReferencedStage(stageName, referenced);
+            if (!found)
+                continue;
+            handler = found.handler;
+            annotatedIn = { sourceFile: found.sourceFile, filePath: found.filePath };
         }
         stages.push(stageName);
         if (stageName === 'getInputData') {
             const parameter = handler.parameters[0];
             if (parameter && !parameter.type) {
-                problems.push({ filePath, message: "getInputData has no type on its first parameter; a run's input shape is read from it." });
+                problems.push({ filePath: annotatedIn.filePath, message: "getInputData has no type on its first parameter; a run's input shape is read from it." });
             }
-            inputType = parameter?.type?.getText(sourceFile);
+            inputType = parameter?.type?.getText(annotatedIn.sourceFile);
         }
         if (stageName === 'summarize') {
             if (!handler.type)
-                problems.push({ filePath, message: "summarize has no return type annotation; a run's result shape is read from it." });
-            resultType = handler.type?.getText(sourceFile);
+                problems.push({ filePath: annotatedIn.filePath, message: "summarize has no return type annotation; a run's result shape is read from it." });
+            resultType = handler.type?.getText(annotatedIn.sourceFile);
         }
     }
     if (!stages.includes('getInputData'))
@@ -162,46 +317,27 @@ function readStages(literal, filePath, sourceFile) {
 }
 export function readJobContract(filePath, source, options) {
     const problems = [];
-    const fileName = nodePath.basename(toPosixPath(filePath));
+    const posixPath = toPosixPath(filePath);
+    const fileName = nodePath.basename(posixPath);
     const nameMatch = jobFileNamePattern.exec(fileName);
     if (!nameMatch)
-        return { problems: [{ filePath, message: 'a job file is named <name>.ts, with <name> in camelCase; nothing else lives in the jobs folder.' }] };
+        return { problems: [{ filePath, message: 'a job is declared in <name>.ts, with <name> in camelCase; nothing else declares a job.' }] };
     const name = nameMatch[1];
+    const folderName = nodePath.basename(nodePath.dirname(posixPath));
+    if (folderName !== name) {
+        problems.push({ filePath, message: `a job lives in a folder of its own name: ${fileName} belongs in a folder called ${name}, beside the stage files it is made of.` });
+    }
     const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
     const header = readScriptTypeHeader(source);
     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 carriedTypeImports = [];
-    const inlinedTypeImports = [];
-    const typeDeclarations = [];
+    const folderFiles = createJobFolderFiles(options);
+    const fileTypes = readFileTypes(sourceFile, filePath, options, folderFiles);
+    problems.push(...fileTypes.problems);
+    const { carriedTypeImports, inlinedTypeImports, declarations: typeDeclarations } = fileTypes;
     let contract;
     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')
-                inlinedTypeImports.push(result.read.typeImport);
-            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.' });
-            }
-            continue;
-        }
-        if (ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement) || ts.isEnumDeclaration(statement)) {
-            if (!hasExportModifier(statement)) {
-                problems.push({ filePath, message: `'${statement.name.text}' is not exported; the generator copies the shapes a run's result names into the browser's module as they are written, so export them.` });
-                continue;
-            }
-            if (statement.name.text === GENERATED_JOB_RESULT_TYPE_NAME) {
-                problems.push({ filePath, message: `type '${statement.name.text}' is the name the generated module gives the run's result; call this shape something else.` });
-                continue;
-            }
-            const jsDoc = readLeadingJsDoc(statement, sourceFile);
-            typeDeclarations.push({ name: statement.name.text, text: `${jsDoc ? `${jsDoc}\n` : ''}${statement.getText(sourceFile)}` });
-            continue;
-        }
         if (!ts.isVariableStatement(statement))
             continue;
         const found = findDefineJobCall(statement);
@@ -225,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);
+        const stages = readStages(stagesArgument, filePath, sourceFile, folderFiles);
         problems.push(...stages.problems);
         for (const exported of found.exportedStages) {
             if (!JOB_STAGE_NAMES.includes(exported)) {
@@ -246,8 +382,18 @@ export function readJobContract(filePath, source, options) {
         }
         if (!declared.script)
             continue;
-        contract = { name, filePath, script: declared.script, inputType: stages.inputType, resultType: stages.resultType, stages: stages.stages, exportedStages: found.exportedStages };
+        contract = {
+            name,
+            filePath,
+            script: declared.script,
+            inputType: stages.inputType,
+            resultType: stages.resultType,
+            stages: stages.stages,
+            exportedStages: found.exportedStages,
+            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.5.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",