@amerilux/netsuite-api 0.4.0 → 0.5.0

package/README.md

@@ -2,11 +2,11 @@
 
 The API layer for a NetSuite single-page app. The app's server side is SuiteScript; its browser side is a bundle served by a Suitelet. This package holds what sits between them, so a project writes controllers and services and nothing else:
 
-- **`@amerilux/netsuite-api/server`**: declare a controller's endpoints and the script that serves them, expose them as a Restlet or a Suitelet, reject a call with an `ApiError`, call another Suitelet controller from server code, and find a File Cabinet file by name.
+- **`@amerilux/netsuite-api/server`**: declare a controller's endpoints and the script that serves them, expose them as a Restlet or a Suitelet, reject a call with an `ApiError`, call another Suitelet controller from server code, write a Map/Reduce job as stages and start one, and find a File Cabinet file by name.
 - **`@amerilux/netsuite-api/client`**: a typed browser client per controller, built from the endpoint types.
 - **`@amerilux/netsuite-api/testing`**: stubs for the `N/*` modules and the vitest wiring that routes imports to them.
-- **`netsuite-api generate`**: reads the controllers and writes the client's whole view of the backend, one module per controller and an index re-exporting them, plus the server-side map of scripts. The client never imports from the server tree.
-- **`@amerilux/netsuite-api`** (the root): the wire itself. The envelope, the endpoint types, `ScriptDeclaration`, `ScriptRef`.
+- **`netsuite-api generate`**: reads the controllers and the jobs and writes the client's whole view of the backend, one module each and an index re-exporting them, plus the server-side map of scripts and jobs. The client never imports from the server tree.
+- **`@amerilux/netsuite-api`** (the root): the wire itself. The envelope, the endpoint types, `ScriptDeclaration`, `ScriptRef`, `JobRef`, `JobRun`.
 
 The layout it assumes is the one `create-netsuite-project` scaffolds: `api/` (SuiteScript) and `client/` (React) as workspaces.
 
@@ -115,6 +115,7 @@ A hook imports `{ customer }` from it, calls `customer.api.search({ search: 'acm
 ```json
 {
   "controllers": "api/src/controllers",
+  "jobs": "api/src/jobs",
   "outDir": "client/src/api",
   "scriptsOutFile": "api/src/scripts.gen.ts",
   "clientModule": "@amerilux/netsuite-api/client",
@@ -124,7 +125,7 @@ A hook imports `{ customer }` from it, calls `customer.api.search({ search: 'acm
 }
 ```
 
-Paths are relative to the config file. `outDir` holds the controller modules and the index, and nothing else. `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. `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
 
@@ -192,9 +193,84 @@ const userRolesApi = createSuiteletClient<UserRolesEndpoints>(scripts.userRoles)
 export const listRolesForEmployee = (employeeId: number) => userRolesApi.byEmployee({ employeeId }).roles;
 ```
 
+## 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.
+
+```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 }
+
+export const { getInputData, map, summarize } = defineJob({
+    name: 'closeStaleOrders',
+    scriptId: 'customscript_app_close_stale_mr',
+    deployments: ['customdeploy_app_close_stale_mr', 'customdeploy_app_close_stale_mr_2'],
+    runParameter: 'custscript_app_close_stale_run',
+    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 }),
+});
+```
+
+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.
+
+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.
+
+```ts
+// api/src/repositories/jobRunRepository.ts
+import { createJobRunStore } from '@amerilux/netsuite-api/server';
+import type { JobRef, JobRun } from '@amerilux/netsuite-api/server';
+import { jobRuns } from '../scripts.gen';
+
+const jobRunStore = createJobRunStore(jobRuns);
+
+export const startJobRun = (job: JobRef, input: unknown): string => jobRunStore.start(job, input);
+export const findJobRun = (runId: string): JobRun | null => jobRunStore.read(runId);
+
+// api/src/services/ordersService.ts
+export const startClosingOldOrders = (olderThanDays: number) => startJobRun(jobs.closeOldOrders, { olderThanDays } satisfies CloseOldOrdersRequest);
+```
+
+`start` writes the run, then submits the task to the first deployment that takes it; NetSuite runs one instance of a deployment at a time, so the list in the declaration is how many runs can overlap. When they are all running it throws `ApiError.conflict` (409) and removes the run it had written, because nothing started. A controller endpoint hands the run id to the browser, which polls another endpoint for `read`.
+
+`read` is the reason a dead run does not look like a working one: it takes status, stage and progress from `N/task.checkStatus` as well as the record, so a task NetSuite gave up on is `failed`, and a task that finished without writing a result is `failed` too. `findExpired(days)` and `remove` are what a cleanup job runs on a schedule; run records are not meant to be permanent.
+
+`findRuns({ job, startedBy, unfinishedOnly, limit })` answers the matching runs newest first, in one query and without loading a record: it is how a page finds the run it lost track of, because the run knows who started it even after a browser has forgotten. Its rows carry what the record says, not what the task says, so read a run by id before believing one is still working — and they carry no progress at all, because only the task has any.
+
+### The run record
+
+The shape is this package's and the ids are the application's, because the record carries the application's prefix. `netsuite-api.config.json` names them and the generator writes them into the scripts map as `jobRuns`:
+
+```json
+"jobRuns": {
+  "recordType": "customrecord_app_job_run",
+  "fieldPrefix": "custrecord_app_jr",
+  "extraFields": { "customerId": { "id": "custrecord_app_jr_customer", "type": "integer" } }
+}
+```
+
+Each field's id is the prefix plus a short suffix (`_job`, `_status`, `_stage`, `_percent`, `_input`, `_result`, `_errors`, `_task`, `_deploy`, `_by`, `_start`, `_end`); `fields` overrides any one of them for a record whose field is named differently. `extraFields` are the fields the application added: `start` sets them (`{ extra: { customerId } }`) and a run reports them back under `extra`, typed.
+
 ## Tests
 
-`N/*` modules exist only inside NetSuite. The `testing` entry ships a stub per module, each export a `vi.fn()`, and the vitest wiring:
+`N/*` modules exist only inside NetSuite. The `testing` entry ships a stub per module, each export a `vi.fn()`, the Map/Reduce contexts a job's stages are called with (`mapContextFor`, `reduceContextFor`, `summarizeContextFor`, each capturing what the stage wrote), and the vitest wiring:
 
 ```ts
 import { inlinedPackagesForNetsuiteStubs, netsuiteModuleStubAliases } from '@amerilux/netsuite-api/testing';

package/dist/client/index.d.ts

@@ -5,4 +5,4 @@
 export { ApiClientError, NETSUITE_API_BASE_PATHS, NO_RESPONSE_STATUS, buildApiUrl, callEndpoint, callRawEndpoint, configureApiClient, createApiClient } from './apiClient.js';
 export type { ApiBasePaths, ApiCallContext, ApiCallOptions, ApiClient, ApiClientConfiguration, ApiClientOptions, ApiErrorHandler, ClientResponse } from './apiClient.js';
 export { ENDPOINT_PARAMETER } from '../index.js';
-export type { ApiEnvelope, ApiErrorBody, Endpoint, Endpoints, EndpointRequest, EndpointResponse, RawResponse, ScriptDeclaration, ScriptKind, ScriptRef } from '../index.js';
+export type { ApiEnvelope, ApiErrorBody, Endpoint, Endpoints, EndpointRequest, EndpointResponse, JobRun, JobRunError, JobRunListEntry, JobRunQuery, JobRunStage, JobRunStatus, RawResponse, ScriptDeclaration, ScriptKind, ScriptRef, } from '../index.js';

package/dist/index.d.ts

@@ -79,3 +79,140 @@ export interface ScriptRef {
     deployId: string;
     browser?: boolean;
 }
+/**
+ * Jobs: the Map/Reduce side of the wire. A job answers nothing, so its run is the thing both sides
+ * talk about: server code starts one and gets a run id, and the browser asks what that run is doing.
+ * A run lives in a record of the application's own (`customrecord_<prefix>_job_run`, whose ids the
+ * generator reads from netsuite-api.config.json), so a job that dies before it writes anything is
+ * still a run that failed, not a page waiting forever.
+ */
+/** How NetSuite stores a script parameter or a run field, and the type the stages and the page see. */
+export type NetsuiteValueType = 'text' | 'integer' | 'decimal' | 'checkbox' | 'date' | 'select';
+/** One script parameter of a job: its id in NetSuite and what NetSuite stores in it. */
+export interface JobParameterDeclaration {
+    id: string;
+    type: NetsuiteValueType;
+}
+/** The value of one parameter as the stages see it. A date arrives as the ISO string, never a Date: a stage is not the wire, but a run record is read by both sides. */
+export type JobParameterValue<TType extends NetsuiteValueType> = TType extends 'integer' | 'decimal' ? number : TType extends 'checkbox' ? boolean : string;
+/** Every parameter a job declares, by the name the stages use. */
+export type JobParameterValues<TParameters extends Record<string, JobParameterDeclaration>> = {
+    readonly [TName in keyof TParameters]: JobParameterValue<TParameters[TName]['type']>;
+};
+/** Where a run is: NetSuite's own stage names, as the run record and the page speak them. */
+export type JobRunStage = 'input' | 'map' | 'shuffle' | 'reduce' | 'summarize';
+/**
+ * A run's state. `pending` is submitted but not started, `running` is anything between, and
+ * `complete` means summarize wrote the result. `failed` is either a stage that threw or a task
+ * NetSuite gave up on, which is why a run is read through checkStatus as well as its record.
+ */
+export type JobRunStatus = 'pending' | 'running' | 'complete' | 'failed';
+/** One thing that went wrong in a run: a stage's own throw, or a key NetSuite could not finish. */
+export interface JobRunError {
+    stage: JobRunStage;
+    /** The key the map or reduce stage was working on, when the failure belongs to one. */
+    key?: string;
+    message: string;
+}
+/**
+ * A run as anyone asking about it sees it: the record's own fields refined by what NetSuite says
+ * about the task. Every time is an ISO string, so this shape crosses to the browser unchanged.
+ */
+export interface JobRun<TResult = unknown, TExtra extends Record<string, unknown> = Record<string, never>> {
+    /** The run record's internal id: what startJob answers and a page polls with. */
+    id: string;
+    /** The job's name, as its declaration gives it. */
+    job: string;
+    status: JobRunStatus;
+    /** The stage the task is in, or null before it starts and after it ends. */
+    stage: JobRunStage | null;
+    /**
+     * How far the stage being processed has got, 0 to 100, as NetSuite reports it. It counts up inside a
+     * stage and starts again at the next one, so it is progress rather than a fraction of the whole run;
+     * a finished run reads 100. For something to put next to a progress bar, prefer the item counts.
+     */
+    stagePercentComplete: number;
+    /** Rows the stage being processed has finished, or null when the task can no longer say. */
+    itemsProcessed: number | null;
+    /** Rows the stage being processed was given, or null when the task can no longer say: a run that has ended, or an id NetSuite has purged. */
+    itemsTotal: number | null;
+    /** The employee who started it, or null for a scheduled run. */
+    startedBy: number | null;
+    startedAt: string | null;
+    finishedAt: string | null;
+    /** The NetSuite task id, kept so a run can be asked about after the fact. */
+    taskId: string | null;
+    /** What summarize returned, once it has. */
+    result: TResult | null;
+    errors: JobRunError[];
+    /** The fields this application added to the run record, as netsuite-api.config.json declares them. */
+    extra: TExtra;
+}
+/**
+ * A run as a list shows it: the fields a query can read, so finding a run costs one query rather than a
+ * record load each. It carries no input, result or errors — a page finds a run here and then asks about
+ * it by id, which is also the only reading that consults the task, so a `running` row in a list is
+ * "last we knew", not a promise. Progress is not here either, for the same reason: only the task has it.
+ */
+export interface JobRunListEntry {
+    id: string;
+    job: string;
+    status: JobRunStatus;
+    stage: JobRunStage | null;
+    startedBy: number | null;
+}
+/** Which runs to list. Every field narrows; the newest are answered first. */
+export interface JobRunQuery {
+    job?: string;
+    /** The employee who started them: how a page finds its own caller's runs again. */
+    startedBy?: number;
+    /** Only runs that have not ended, for "is one of these already going?". */
+    unfinishedOnly?: boolean;
+    /** How many, newest first. Defaults to 10, capped at 100. */
+    limit?: number;
+}
+/** One deployed job as server code starts it: `scripts.<job>` in the generated scripts map. */
+export interface JobRef {
+    kind: 'mapreduce';
+    /** The job's name, as its declaration gives it and the run record records it. */
+    name: string;
+    scriptId: string;
+    /**
+     * Every deployment the job may run on, in the order they are tried. NetSuite runs one instance of
+     * a deployment at a time, so this list is how many runs of the job can overlap.
+     */
+    deployments: readonly string[];
+    /** The script parameter the run id is passed in; every stage reads the run back from it. */
+    runParameter: string;
+    /** The job's own script parameters, by the name the stages use. */
+    parameters?: Readonly<Record<string, string>>;
+}
+/** One field an application added to its run record, as netsuite-api.config.json declares it. */
+export interface JobRunExtraField {
+    id: string;
+    type: NetsuiteValueType;
+}
+/**
+ * The run record as this application deployed it, written by the generator from the `jobRuns` block
+ * of netsuite-api.config.json. The field names are the package's; their ids are the application's,
+ * because the record carries the application's prefix.
+ */
+export interface JobRunsConfig {
+    recordType: string;
+    fields: {
+        job: string;
+        status: string;
+        stage: string;
+        stagePercentComplete: string;
+        input: string;
+        result: string;
+        errors: string;
+        taskId: string;
+        deployment: string;
+        startedBy: string;
+        startedAt: string;
+        finishedAt: string;
+    };
+    /** Fields this application added, by the name the code uses for them. */
+    extraFields: Readonly<Record<string, JobRunExtraField>>;
+}

package/dist/server/apiError.d.ts

@@ -6,4 +6,6 @@ export declare class ApiError extends Error {
     static badRequest(message: string, details?: unknown): ApiError;
     static notFound(message: string, details?: unknown): ApiError;
     static forbidden(message?: string): ApiError;
+    /** The request was fine but the account cannot take it now: every deployment of a job is already running. */
+    static conflict(message: string, details?: unknown): ApiError;
 }

package/dist/server/apiError.js

@@ -15,4 +15,8 @@ export class ApiError extends Error {
     static forbidden(message = 'Not permitted') {
         return new ApiError(403, message);
     }
+    /** The request was fine but the account cannot take it now: every deployment of a job is already running. */
+    static conflict(message, details) {
+        return new ApiError(409, message, details);
+    }
 }

package/dist/server/defineJob.d.ts

@@ -0,0 +1,95 @@
+import type { EntryPoints } from 'N/types';
+import type { JobParameterDeclaration, JobParameterValues, JobRunError, JobRunsConfig } from '../index.js';
+/**
+ * A job is a Map/Reduce script written as stages instead of entry points:
+ *
+ *     export const { getInputData, map, summarize } = defineJob({
+ *         name: 'closeStaleOrders',
+ *         scriptId: 'customscript_app_close_stale_orders_mr',
+ *         deployments: ['customdeploy_app_close_stale_orders_mr', 'customdeploy_app_close_stale_orders_mr_2'],
+ *         runParameter: 'custscript_app_close_stale_run',
+ *         runs: jobRuns,
+ *     }, {
+ *         getInputData: (input: CloseStaleRequest): StaleOrder[] => listStaleOrders(input.olderThanDays),
+ *         map: (order: StaleOrder, job) => { job.write(String(order.id), closeOrder(order.id)); },
+ *         summarize: (summary): CloseStaleResult => ({ closed: summary.output.length }),
+ *     });
+ *
+ * What the wrapper adds is the run: the values between stages are typed and parsed, getInputData's
+ * input comes from the run record rather than a parameter the stage has to decode, summarize's
+ * return value becomes the run's result, and the errors NetSuite collected are written onto the run
+ * with it. A stage that throws marks the run failed and rethrows, so the failure is in the execution
+ * log where NetSuite puts it and on the run where the page is looking.
+ *
+ * Export the stages the job has. Every job exports summarize even when it has no summarize stage of
+ * its own, because that is where the run is closed. A stage exported but not declared throws when
+ * NetSuite calls it, rather than quietly passing values through.
+ */
+/** A job's script: what the generator reads, and what the run record's rows point back at. */
+export interface JobDeclaration<TParameters extends Record<string, JobParameterDeclaration> = Record<string, never>> {
+    /** The job's name, as the run record records it and the scripts map keys it: the file name. */
+    name: string;
+    /** The script record's id, `customscript_<prefix>_<name>_mr`. */
+    scriptId: string;
+    /**
+     * Every deployment of the script, in the order startJob tries them. NetSuite runs one instance of
+     * a deployment at a time, so the length of this list is how many runs can overlap; a job started
+     * from a page answers 409 when they are all busy.
+     */
+    deployments: string[];
+    /** The script parameter carrying the run id, `custscript_<prefix>_<name>_run`. */
+    runParameter: string;
+    /** The job's own script parameters, by the name the stages use. */
+    parameters?: TParameters;
+    /** The application's run record, from the generated scripts map: `runs: jobRuns`. */
+    runs: JobRunsConfig;
+}
+/** What every stage is given besides its own values. */
+export interface JobContext<TParameters extends Record<string, JobParameterDeclaration>> {
+    /** The run this stage belongs to, as the page polls it. */
+    readonly runId: string;
+    /** The script parameters the declaration names, typed. */
+    readonly parameters: JobParameterValues<TParameters>;
+}
+/** A stage that writes values for the stage after it. */
+export interface JobWriteContext<TParameters extends Record<string, JobParameterDeclaration>, TValue> extends JobContext<TParameters> {
+    /** Hands one value to the next stage under a key; the value is carried as JSON and comes back typed. */
+    write(key: string, value: TValue): void;
+}
+/** What the run produced, as summarize sees it. */
+export interface JobSummary<TOutput> {
+    /** Every key and value the reduce stage wrote, or the map stage's when the job has no reduce. */
+    output: {
+        key: string;
+        value: TOutput;
+    }[];
+    /** Everything that failed anywhere in the run; these are written onto the run whatever summarize returns. */
+    errors: JobRunError[];
+    seconds: number;
+    usage: number;
+    concurrency: number;
+    yields: number;
+}
+/**
+ * The stages of a job. getInputData's first parameter is the run's input and summarize's return type
+ * is the run's result: the generator reads both from those annotations, the way it reads an endpoint's
+ * request and response. The items getInputData returns are typed from there on.
+ *
+ * The values between map, reduce and summarize are carried as JSON, so each stage says what it
+ * expects: a reduce stage writes `values: number[]` and a summarize stage `summary: JobSummary<Total>`,
+ * and the wrapper hands them back as annotated. The stages are written as methods for that reason.
+ */
+export interface JobStages<TInput, TItem, TValue = unknown, TOutput = unknown, TResult = null, TParameters extends Record<string, JobParameterDeclaration> = Record<string, never>> {
+    getInputData(input: TInput, job: JobContext<TParameters>): TItem[] | Record<string, TItem>;
+    map?(item: TItem, job: JobWriteContext<TParameters, TValue>): void;
+    reduce?(key: string, values: TValue[], job: JobWriteContext<TParameters, TOutput>): void;
+    summarize?(summary: JobSummary<TOutput>, job: JobContext<TParameters>): TResult;
+}
+/** The four NetSuite entry points, of which a job file exports the ones it has. */
+export interface JobEntryPoints {
+    getInputData: (context: EntryPoints.MapReduce.getInputDataContext) => unknown;
+    map: (context: EntryPoints.MapReduce.mapContext) => void;
+    reduce: (context: EntryPoints.MapReduce.reduceContext) => void;
+    summarize: (context: EntryPoints.MapReduce.summarizeContext) => void;
+}
+export declare function defineJob<TInput, TItem, TValue = unknown, TOutput = unknown, TResult = null, TParameters extends Record<string, JobParameterDeclaration> = Record<string, never>>(declaration: JobDeclaration<TParameters>, stages: JobStages<TInput, TItem, TValue, TOutput, TResult, TParameters>): JobEntryPoints;

package/dist/server/defineJob.js

@@ -0,0 +1,150 @@
+import * as log from 'N/log';
+import * as runtime from 'N/runtime';
+import { createJobRunStore } from './jobRuns.js';
+function readParameterValue(id, type) {
+    const raw = runtime.getCurrentScript().getParameter({ name: id });
+    if (raw === null || raw === undefined || raw === '')
+        return type === 'checkbox' ? false : type === 'integer' || type === 'decimal' ? 0 : '';
+    if (type === 'integer' || type === 'decimal')
+        return Number(raw);
+    if (type === 'checkbox')
+        return raw === true || raw === 'T' || raw === 'true';
+    if (raw instanceof Date)
+        return raw.toISOString();
+    return String(raw);
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** The errors NetSuite collected, in the order the run met them. */
+function readCollectedErrors(summary) {
+    var _a;
+    const errors = [];
+    if ((_a = summary.inputSummary) === null || _a === void 0 ? void 0 : _a.error)
+        errors.push({ stage: 'input', message: summary.inputSummary.error });
+    const collect = (stage, container) => {
+        container === null || container === void 0 ? void 0 : container.errors.iterator().each((key, error) => {
+            errors.push({ stage, key, message: error });
+            return true;
+        });
+    };
+    collect('map', summary.mapSummary);
+    collect('reduce', summary.reduceSummary);
+    return errors;
+}
+export function defineJob(declaration, stages) {
+    const store = createJobRunStore(declaration.runs);
+    const { name } = declaration;
+    const readParameters = () => {
+        var _a;
+        const values = {};
+        for (const [parameterName, parameter] of Object.entries((_a = declaration.parameters) !== null && _a !== void 0 ? _a : {}))
+            values[parameterName] = readParameterValue(parameter.id, parameter.type);
+        return values;
+    };
+    const readRunIdParameter = () => {
+        const raw = runtime.getCurrentScript().getParameter({ name: declaration.runParameter });
+        return typeof raw === 'string' && raw !== '' ? raw : undefined;
+    };
+    /**
+     * The run a stage belongs to. getInputData has it from the parameter or opens one; the stages
+     * after it read the parameter again, and a scheduled run (which has no parameter to read) is
+     * found by the deployment it is running on, one run at a time being all a deployment can do.
+     */
+    const buildContext = (runIdSource) => {
+        let resolvedRunId;
+        let resolvedParameters;
+        return {
+            get runId() {
+                resolvedRunId = resolvedRunId !== null && resolvedRunId !== void 0 ? resolvedRunId : runIdSource();
+                return resolvedRunId;
+            },
+            get parameters() {
+                resolvedParameters = resolvedParameters !== null && resolvedParameters !== void 0 ? resolvedParameters : readParameters();
+                return resolvedParameters;
+            },
+        };
+    };
+    const lateRunId = () => {
+        var _a, _b;
+        const deployment = String(runtime.getCurrentScript().deploymentId);
+        return (_b = (_a = readRunIdParameter()) !== null && _a !== void 0 ? _a : store.findRunningRunId(name, deployment)) !== null && _b !== void 0 ? _b : '';
+    };
+    /** A stage's own failure: logged, written onto the run when the run is the only place it would show, and rethrown for NetSuite. */
+    const runStage = (stage, context, markRun, work) => {
+        try {
+            return work();
+        }
+        catch (error) {
+            const message = describeError(error);
+            log.error('job stage failed', { job: name, stage, runId: context.runId, message });
+            if (markRun && context.runId !== '')
+                store.fail(context.runId, { stage, message });
+            throw error;
+        }
+    };
+    return {
+        getInputData(scriptContext) {
+            const deployment = String(runtime.getCurrentScript().deploymentId);
+            const runId = store.claimRun({ job: name, runId: readRunIdParameter(), deployment });
+            const context = buildContext(() => runId);
+            log.audit('job started', { job: name, runId, deployment, restarted: scriptContext.isRestarted });
+            return runStage('input', context, true, () => stages.getInputData(store.readInput(runId), context));
+        },
+        map(scriptContext) {
+            const context = buildContext(lateRunId);
+            runStage('map', context, false, () => {
+                if (!stages.map)
+                    throw new Error(`${name} declares no map stage; remove map from this file's exports.`);
+                stages.map(JSON.parse(scriptContext.value), {
+                    get runId() {
+                        return context.runId;
+                    },
+                    get parameters() {
+                        return context.parameters;
+                    },
+                    write: (key, value) => scriptContext.write({ key, value: JSON.stringify(value) }),
+                });
+            });
+        },
+        reduce(scriptContext) {
+            const context = buildContext(lateRunId);
+            runStage('reduce', context, false, () => {
+                if (!stages.reduce)
+                    throw new Error(`${name} declares no reduce stage; remove reduce from this file's exports.`);
+                stages.reduce(scriptContext.key, scriptContext.values.map((value) => JSON.parse(value)), {
+                    get runId() {
+                        return context.runId;
+                    },
+                    get parameters() {
+                        return context.parameters;
+                    },
+                    write: (key, value) => scriptContext.write({ key, value: JSON.stringify(value) }),
+                });
+            });
+        },
+        summarize(scriptContext) {
+            var _a;
+            const context = buildContext(lateRunId);
+            const errors = readCollectedErrors(scriptContext);
+            const output = [];
+            scriptContext.output.iterator().each((key, value) => {
+                output.push({ key, value: JSON.parse(value) });
+                return true;
+            });
+            const summary = {
+                output,
+                errors,
+                seconds: scriptContext.seconds,
+                usage: scriptContext.usage,
+                concurrency: scriptContext.concurrency,
+                yields: scriptContext.yields,
+            };
+            const result = runStage('summarize', context, true, () => (stages.summarize ? stages.summarize(summary, context) : null));
+            const status = ((_a = scriptContext.inputSummary) === null || _a === void 0 ? void 0 : _a.error) ? 'failed' : 'complete';
+            if (context.runId !== '')
+                store.finish(context.runId, { status, result, errors });
+            log.audit('job finished', { job: name, runId: context.runId, status, errors: errors.length, seconds: scriptContext.seconds, usage: scriptContext.usage });
+        },
+    };
+}

package/dist/server/index.d.ts

@@ -1,12 +1,17 @@
 /**
  * The server side of the API: declare a controller's endpoints, expose them as a Restlet or a
  * Suitelet, reject a call with an ApiError, authorize calls, answer with a document instead of JSON,
- * call another Suitelet controller from server code, and find a File Cabinet file by name. Runs
- * inside NetSuite only; the modules here import N/*.
+ * call another Suitelet controller from server code, write a Map/Reduce job and the record its runs
+ * live in, and find a File Cabinet file by name. Runs inside NetSuite only; the modules here import
+ * N/*.
  */
 export { ApiError } from './apiError.js';
 export { defineEndpoints, invokeEndpoint, parseEndpointRequest, readEndpointCall } from './endpoint.js';
 export type { AuthorizeEndpoint, ControllerOptions, EndpointCall, EndpointCallContext, EndpointOutcome, InvokeEndpointOptions } from './endpoint.js';
+export { defineJob } from './defineJob.js';
+export type { JobContext, JobDeclaration, JobEntryPoints, JobStages, JobSummary, JobWriteContext } from './defineJob.js';
+export { createJobRunStore } from './jobRuns.js';
+export type { ClaimRunDetails, FinishRunOutcome, JobRunStore, StartJobOptions } from './jobRuns.js';
 export { defineRestlet } from './defineRestlet.js';
 export type { RestletEntryPoint } from './defineRestlet.js';
 export { defineSuitelet } from './defineSuitelet.js';
@@ -18,4 +23,4 @@ export type { SuiteletClient } from './suiteletClient.js';
 export { findFileId, findFolderId, getFileUrlByName } from './fileCabinet.js';
 export type { FileCabinetLocation } from './fileCabinet.js';
 export { ENDPOINT_PARAMETER } from '../index.js';
-export type { ApiEnvelope, ApiErrorBody, Endpoint, Endpoints, EndpointRequest, EndpointResponse, RawResponse, ScriptDeclaration, ScriptKind, ScriptRef } from '../index.js';
+export type { ApiEnvelope, ApiErrorBody, Endpoint, Endpoints, EndpointRequest, EndpointResponse, JobParameterDeclaration, JobParameterValue, JobParameterValues, JobRef, JobRun, JobRunError, JobRunListEntry, JobRunQuery, JobRunExtraField, JobRunsConfig, JobRunStage, JobRunStatus, NetsuiteValueType, RawResponse, ScriptDeclaration, ScriptKind, ScriptRef, } from '../index.js';

package/dist/server/index.js

@@ -1,11 +1,14 @@
 /**
  * The server side of the API: declare a controller's endpoints, expose them as a Restlet or a
  * Suitelet, reject a call with an ApiError, authorize calls, answer with a document instead of JSON,
- * call another Suitelet controller from server code, and find a File Cabinet file by name. Runs
- * inside NetSuite only; the modules here import N/*.
+ * call another Suitelet controller from server code, write a Map/Reduce job and the record its runs
+ * live in, and find a File Cabinet file by name. Runs inside NetSuite only; the modules here import
+ * N/*.
  */
 export { ApiError } from './apiError.js';
 export { defineEndpoints, invokeEndpoint, parseEndpointRequest, readEndpointCall } from './endpoint.js';
+export { defineJob } from './defineJob.js';
+export { createJobRunStore } from './jobRuns.js';
 export { defineRestlet } from './defineRestlet.js';
 export { defineSuitelet } from './defineSuitelet.js';
 export { isRawResponse, rawResponse, writeRawResponse } from './rawResponse.js';

package/dist/server/jobRuns.d.ts

@@ -0,0 +1,65 @@
+import type { JobRef, JobRun, JobRunError, JobRunListEntry, JobRunQuery, JobRunStatus, JobRunsConfig } from '../index.js';
+/**
+ * The run record: everything a job run is, outside the job. A Map/Reduce script answers nothing and
+ * cannot be waited on, so starting one writes a record first and passes its id in as the script
+ * parameter; the stages read their input back from it and summarize writes the result to it. Reading
+ * a run asks NetSuite about the task as well, which is what tells a run that died apart from one
+ * still working: a record left at `running` under a task NetSuite has finished or given up on is a
+ * failure, not something to keep polling.
+ *
+ * The record is the application's own (`customrecord_<prefix>_job_run`), so the ids come in as the
+ * generated `jobRuns` config rather than being written here. A repository builds the store once and
+ * the jobs build their own from the same config; nothing is global.
+ */
+/** What startJob may add to the run beyond the input: the application's own fields on the run record. */
+export interface StartJobOptions {
+    /** Values for the fields declared in `jobRuns.extraFields`, by name. */
+    extra?: Record<string, unknown>;
+}
+/** What a stage's wrapper needs to find or open a run; not used by application code. */
+export interface ClaimRunDetails {
+    job: string;
+    /** The run id the script parameter carried, or undefined for a scheduled run, which opens its own. */
+    runId?: string;
+    deployment: string;
+}
+/** How a run ended, as summarize leaves it. */
+export interface FinishRunOutcome {
+    status: Extract<JobRunStatus, 'complete' | 'failed'>;
+    result: unknown;
+    errors: JobRunError[];
+}
+export interface JobRunStore {
+    /**
+     * Starts a job: writes the run, then submits the task to the first deployment that takes it. The
+     * run id is what a page polls with. Throws a 409 when every deployment is already running, and
+     * leaves no run behind when it does, because nothing started.
+     */
+    start(job: JobRef, input?: unknown, options?: StartJobOptions): string;
+    /** The run as anyone asking sees it: the record refined by what NetSuite says about the task. Null when the record is gone (cleaned up, or never existed). */
+    read<TResult = unknown, TExtra extends Record<string, unknown> = Record<string, never>>(runId: string): JobRun<TResult, TExtra> | null;
+    /**
+     * The runs matching the query, newest first: one query, no record loads, so a page can find the run it
+     * lost track of. The rows carry what the record says and not what the task says, so read a run by id
+     * before believing it is still working.
+     */
+    findRuns(runQuery?: JobRunQuery): JobRunListEntry[];
+    /** Run ids older than the given number of days, for the cleanup job. */
+    findExpired(olderThanDays: number): string[];
+    remove(runId: string): void;
+    /** Opens the run a stage belongs to, creating one for a scheduled run. Called by the job wrapper. */
+    claimRun(details: ClaimRunDetails): string;
+    /** The input the run was started with; `{}` for a scheduled run. Called by the job wrapper. */
+    readInput<TInput>(runId: string): TInput;
+    /** The run id of whatever is running on this deployment, for the stages after getInputData. Called by the job wrapper. */
+    findRunningRunId(job: string, deployment: string): string | undefined;
+    /** Writes the result and the errors, and closes the run. Called by the job wrapper. */
+    finish(runId: string, outcome: FinishRunOutcome): void;
+    /** Marks the run failed with one error, for a stage that threw. Called by the job wrapper. */
+    fail(runId: string, error: JobRunError): void;
+}
+/**
+ * The store for one application's run record. Build it once where it is used: a repository for the
+ * application's own calls, and the job wrapper for the stages.
+ */
+export declare function createJobRunStore(config: JobRunsConfig): JobRunStore;