@amerilux/netsuite-api 0.4.0 → 0.6.0

package/dist-tooling/generate.js

@@ -1,7 +1,8 @@
 import * as nodePath from 'node:path';
-import { resolveInlineTypesFile } from './config.js';
+import { resolveInlineTypesFile, resolveJobRunFieldIds } from './config.js';
 import { isControllerFileName, readControllerContract } from './controllerReader.js';
-import { CLIENT_INDEX_FILE_NAME, controllerModuleFileName, emitClientIndexModule, emitControllerModule, emitScriptsModule, sortControllers } from './emit.js';
+import { CLIENT_INDEX_FILE_NAME, JOBS_INDEX_FILE_NAME, controllerModuleFileName, emitClientIndexModule, emitControllerModule, emitJobModule, emitJobsIndexModule, 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';
 import { readReferencedNames } from './wireTypes.js';
@@ -9,35 +10,71 @@ const generatedFileNamePattern = /\.gen\.ts$/;
 function relativeLabel(rootDirectory, filePath) {
     return toPosixPath(nodePath.relative(rootDirectory, filePath));
 }
-function findDuplicateScriptIds(controllers) {
+function findDuplicateScriptIds(controllers, jobs) {
     const problems = [];
-    for (const property of ['scriptId', 'deployId']) {
-        const owners = new Map();
-        for (const { contract } of controllers) {
-            const id = contract.script[property];
-            const owner = owners.get(id);
-            if (owner !== undefined)
-                problems.push({ filePath: contract.filePath, message: `${property} '${id}' is also declared by ${owner}; every controller is its own script.` });
-            else
-                owners.set(id, contract.filePath);
-        }
+    const scriptOwners = new Map();
+    const deployOwners = new Map();
+    const claim = (owners, id, filePath, label) => {
+        const owner = owners.get(id);
+        if (owner !== undefined)
+            problems.push({ filePath, message: `${label} '${id}' is also declared by ${owner}; every controller and every job is its own script.` });
+        else
+            owners.set(id, filePath);
+    };
+    for (const { contract } of controllers) {
+        claim(scriptOwners, contract.script.scriptId, contract.filePath, 'scriptId');
+        claim(deployOwners, contract.script.deployId, contract.filePath, 'deployId');
+    }
+    for (const { contract } of jobs) {
+        claim(scriptOwners, contract.script.scriptId, contract.filePath, 'scriptId');
+        for (const deployment of contract.script.deployments)
+            claim(deployOwners, deployment, contract.filePath, 'deployment');
     }
     return problems;
 }
-/**
- * A Date reached from a request shape, through the controller's own declarations and the copied
- * ones: the handler would receive an ISO string where its annotation promises a Date. (A shape taken
- * from a sibling controller is checked where it is declared, as that controller's own request.)
- */
-function findDatesInRequestShapes(contract, inlinedTypes, controllerLabel) {
+/** Every type declaration a shape can be built from: the file's own, then the ones copied into it. */
+function collectDeclarations(own, inlinedTypes) {
     const declarations = new Map();
-    for (const declaration of contract.typeDeclarations)
+    for (const declaration of own)
         declarations.set(declaration.name, declaration.text);
     for (const section of inlinedTypes) {
         for (const declaration of section.declarations)
             if (!declarations.has(declaration.name))
                 declarations.set(declaration.name, declaration.text);
     }
+    return declarations;
+}
+/**
+ * A Date reached from a run's input: it is stored as JSON on the run record, so the stage would
+ * receive an ISO string where its annotation promises a Date. The result is not checked, because
+ * nothing reads it back as a Date; the browser sees whatever summarize wrote.
+ */
+function findDatesInJobInput(contract, inlinedTypes, jobLabel) {
+    if (contract.inputType === undefined)
+        return [];
+    const declarations = collectDeclarations(contract.typeDeclarations, inlinedTypes);
+    const visited = new Set();
+    const pending = readReferencedNames(contract.inputType, 'type').map((name) => ({ name, via: contract.inputType }));
+    while (pending.length > 0) {
+        const { name, via } = pending.shift();
+        if (name === 'Date') {
+            return [{ filePath: jobLabel, message: `getInputData takes a Date in its input (through ${via}); a run carries its input as JSON, so take a string and parse it in the stage.` }];
+        }
+        const text = declarations.get(name);
+        if (text === undefined || visited.has(name))
+            continue;
+        visited.add(name);
+        pending.push(...readReferencedNames(text, 'declaration').map((reference) => ({ name: reference, via: name })));
+    }
+    return [];
+}
+/**
+ * A Date reached from a request shape, through the controller's own declarations and the copied
+ * ones: the handler would receive an ISO string where its annotation promises a Date. (A shape taken
+ * from a sibling controller is checked where it is declared, as that controller's own request.)
+ */
+function findDatesInRequestShapes(contract, inlinedTypes, controllerLabel) {
+    const declarations = collectDeclarations(contract.typeDeclarations, inlinedTypes);
     const problems = [];
     for (const endpoint of contract.endpoints) {
         if (endpoint.requestType === undefined)
@@ -132,7 +169,78 @@ export function planClientGeneration({ config, fileSystem }) {
         problems.push(...findDatesInRequestShapes(contract, inlinedTypes, controllerLabel));
         emitted.push({ contract, sourceLabel: controllerLabel, inlinedTypes });
     }
-    problems.push(...findDuplicateScriptIds(emitted));
+    // 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 = [];
+    /** 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 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)
+            continue;
+        if (controllerNames.has(contract.name) && jobModuleFileName(contract.name) === controllerModuleFileName(contract.name)) {
+            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);
+        }
+        for (const typeImport of contract.inlinedTypeImports)
+            addInlinedTypes(inlinedTypes, typeImport, jobLabel);
+        problems.push(...findDatesInJobInput(contract, inlinedTypes, jobLabel));
+        emittedJobs.push({ contract, sourceLabel: jobLabel, inlinedTypes });
+    }
+    if (emittedJobs.length > 0 && config.jobRuns === undefined) {
+        problems.push({
+            filePath: label(jobsDirectory),
+            message: 'the project has jobs but no run record: add the `jobRuns` block to netsuite-api.config.json (`npm run add:jobs` writes it, with the record itself).',
+        });
+    }
+    problems.push(...findDuplicateScriptIds(emitted, emittedJobs));
     const controllers = emitted.map(({ contract }) => ({
         name: contract.name,
         filePath: contract.filePath,
@@ -140,19 +248,31 @@ export function planClientGeneration({ config, fileSystem }) {
         browser: contract.script.browser,
         endpointCount: contract.endpoints.length,
     }));
+    const jobs = emittedJobs.map(({ contract }) => ({
+        name: contract.name,
+        filePath: contract.filePath,
+        stages: contract.stages,
+        deploymentCount: contract.script.deployments.length,
+    }));
     if (problems.length > 0)
-        return { files: [], leftoverFiles: [], controllers, problems };
+        return { files: [], leftoverFiles: [], controllers, jobs, problems };
     const controllersLabel = label(controllersDirectory);
+    const jobsLabel = label(jobsDirectory);
+    const jobRuns = config.jobRuns
+        ? { recordType: config.jobRuns.recordType, fields: resolveJobRunFieldIds(config.jobRuns), extraFields: config.jobRuns.extraFields ?? {} }
+        : undefined;
     const files = [
         ...sortControllers(emitted).map((controller) => ({
             path: nodePath.join(outDirectory, controllerModuleFileName(controller.contract.name)),
             content: emitControllerModule(controller, { clientModule: config.clientModule }),
         })),
-        { path: nodePath.join(outDirectory, CLIENT_INDEX_FILE_NAME), content: emitClientIndexModule(emitted, { controllersLabel }) },
-        { path: resolve(config.scriptsOutFile), content: emitScriptsModule(emitted, { wireModule: config.wireModule, controllersLabel }) },
+        ...sortJobs(emittedJobs).map((job) => ({ path: nodePath.join(outDirectory, jobModuleFileName(job.contract.name)), content: emitJobModule(job) })),
+        ...(emittedJobs.length > 0 ? [{ path: nodePath.join(outDirectory, JOBS_INDEX_FILE_NAME), content: emitJobsIndexModule(emittedJobs, { jobsLabel }) }] : []),
+        { path: nodePath.join(outDirectory, CLIENT_INDEX_FILE_NAME), content: emitClientIndexModule(emitted, { controllersLabel, hasJobs: emittedJobs.length > 0 }) },
+        { path: resolve(config.scriptsOutFile), content: emitScriptsModule(emitted, { wireModule: config.wireModule, controllersLabel, jobs: emittedJobs, jobsLabel, jobRuns }) },
     ];
     const leftoverFiles = findLeftoverFiles(fileSystem, outDirectory, files.map((file) => file.path));
-    return { files, leftoverFiles, controllers, problems };
+    return { files, leftoverFiles, controllers, jobs, problems };
 }
 export function runClientGeneration(options) {
     const plan = planClientGeneration(options);

package/dist-tooling/index.d.ts

@@ -1,14 +1,17 @@
 /** The generator as a library: what the `netsuite-api` command runs, for a build tool or a test to call directly. */
 export { DEFAULT_CONFIG_FILE_NAME, ClientGeneratorConfigError, defaultClientGeneratorConfig, loadClientGeneratorConfig } from './config.js';
-export type { ClientGeneratorConfig, ResolvedClientGeneratorConfig } from './config.js';
+export { JOB_RUN_FIELD_SUFFIXES, netsuiteValueTypeNames, resolveJobRunFieldIds } from './config.js';
+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, 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';
-export { CLIENT_INDEX_FILE_NAME, controllerModuleFileName, emitClientIndexModule, emitControllerModule, emitScriptsModule } from './emit.js';
-export type { EmitClientIndexModuleOptions, EmitControllerModuleOptions, EmitScriptsModuleOptions, EmittedController, InlinedTypeSection } from './emit.js';
+export { CLIENT_INDEX_FILE_NAME, JOBS_INDEX_FILE_NAME, controllerModuleFileName, emitClientIndexModule, emitControllerModule, emitJobModule, emitJobsIndexModule, emitScriptsModule, jobModuleFileName } from './emit.js';
+export type { EmitClientIndexModuleOptions, EmitControllerModuleOptions, EmitScriptsModuleOptions, EmittedController, EmittedJob, EmittedJobRuns, InlinedTypeSection } from './emit.js';
 export { checkClientGeneration, planClientGeneration, runClientGeneration } from './generate.js';
-export type { ClientGenerationCheck, ClientGenerationPlan, ClientGenerationResult, GenerateClientOptions, PlannedController, PlannedFile } from './generate.js';
+export type { ClientGenerationCheck, ClientGenerationPlan, ClientGenerationResult, GenerateClientOptions, PlannedController, PlannedFile, PlannedJob } from './generate.js';
 export { createInMemoryFileSystemAdapter, createNodeFileSystemAdapter, toPosixPath } from './file-system.js';
 export type { FileSystemAdapter, InMemoryFileSystemAdapter } from './file-system.js';
 export { CLI_USAGE, EXIT_PROBLEMS, EXIT_SUCCESS, EXIT_USAGE, runCli } from './cli/main.js';

package/dist-tooling/index.js

@@ -1,8 +1,10 @@
 /** The generator as a library: what the `netsuite-api` command runs, for a build tool or a test to call directly. */
 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, jobDefinitionFileName, readJobContract, readJobFolderName } from './jobReader.js';
 export { readInlinableTypesFile, selectInlinedTypes } from './typesFileReader.js';
-export { CLIENT_INDEX_FILE_NAME, controllerModuleFileName, emitClientIndexModule, emitControllerModule, emitScriptsModule } from './emit.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';
 export { createInMemoryFileSystemAdapter, createNodeFileSystemAdapter, toPosixPath } from './file-system.js';
 export { CLI_USAGE, EXIT_PROBLEMS, EXIT_SUCCESS, EXIT_USAGE, runCli } from './cli/main.js';

package/dist-tooling/jobReader.d.ts

@@ -0,0 +1,83 @@
+import type { CarriedTypeImport, ControllerProblem, InlinedTypeImport, ReadControllerOptions, TypeDeclaration } from './controllerReader.js';
+/**
+ * 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"];
+export type JobStageName = (typeof JOB_STAGE_NAMES)[number];
+/** The script type a job's leading JSDoc must declare. */
+export declare 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 declare const GENERATED_JOB_RESULT_TYPE_NAME = "Result";
+declare const netsuiteValueTypes: readonly ["text", "integer", "decimal", "checkbox", "date", "select"];
+export interface JobParameterContract {
+    /** The name the stages read it by. */
+    name: string;
+    id: string;
+    type: (typeof netsuiteValueTypes)[number];
+}
+/** The script a job declares, as read off its defineJob call. */
+export interface DeclaredJob {
+    scriptId: string;
+    deployments: string[];
+    runParameter: string;
+    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.
+ */
+export interface JobStageFile {
+    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;
+    filePath: string;
+    script: DeclaredJob;
+    carriedTypeImports: CarriedTypeImport[];
+    inlinedTypeImports: InlinedTypeImport[];
+    typeDeclarations: TypeDeclaration[];
+    /** The type of getInputData's first parameter, or undefined when a run takes no input. */
+    inputType?: string;
+    /** What summarize returns, or undefined when the job has no summarize stage of its own. */
+    resultType?: string;
+    /** The stages the job declares. */
+    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[];
+}
+export interface JobReadResult {
+    contract?: JobContract;
+    problems: ControllerProblem[];
+}
+/** 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 {};