@amerilux/netsuite-api 0.2.1 → 0.4.0

package/README.md

@@ -45,7 +45,7 @@ export const post = defineRestlet({
 }, customerEndpoints);
 ```
 
-Every call is a POST whose JSON body carries the request plus an `endpoint` property naming the endpoint. The handler answers with data, or throws an `ApiError` for a status the caller should see; anything else is a 500 with the details logged. A Suitelet controller is the same file with `defineSuitelet` and `onRequest` instead, and `browser: false` in the declaration when only server code calls it.
+Every call is a POST whose JSON body carries the request plus an `endpoint` property naming the endpoint. The handler answers with data, or throws an `ApiError` for a status the caller should see, with a `details` object the caller can act on (a per-field validation map, the offending id) that travels in the envelope; anything else is a 500 whose cause is logged and never sent. A Suitelet controller is the same file with `defineSuitelet` and `onRequest` instead, and `browser: false` in the declaration when only server code calls it.
 
 The declaration is the controller's own statement of the script it is deployed as. It creates nothing: the controller builds, tests and bundles before any script record exists. The ids are how a client reaches the controller once it is deployed, so set them to whatever the record and deployment are called in NetSuite and in the SDF object; the generator wires every client to them.
 
@@ -53,7 +53,7 @@ The generator reads the file as source, so a few things are rules rather than co
 
 - Handlers are written inline with their parameter and return types annotated. A reference to a service function carries no types the generator can read.
 - Every type in the file is a wire shape and is exported.
-- A type is imported only from the inlined files (the generated entity types, by default), the carried modules (the package's server entry, for `RawResponse`) or another controller. A service's return type is never used as a DTO by reference.
+- A type is imported only from the inlined files (by default the generated entity types and the services: what a service returns is the domain type a wire shape is built from), the carried modules (the package's server entry, for `RawResponse`) or another controller. A service's function is never referenced by the handler in place of an annotation.
 - The script declaration is an object literal with literal ids, its `name` is the file name without `Controller`, and the entry point export and the `@NScriptType` header agree with the define function.
 - Script ids are unique across controllers, and no wire shape is named `Endpoints`. A shape's name carries no controller prefix: each controller's generated module is its own namespace.
 
@@ -67,7 +67,7 @@ The generator reads the file as source, so a few things are rules rather than co
 // client/src/api/customer.gen.ts
 import { createApiClient } from '@amerilux/netsuite-api/client';
 
-// Entity types from api/src/types/models.gen.ts, copied so this module stands on its own.
+// Types from api/src/types/models.gen.ts, copied so this module stands on its own.
 
 export interface Customer {
     id: number;
@@ -91,7 +91,9 @@ export type Endpoints = {
 export const api = createApiClient<Endpoints>({ kind: 'restlet', scriptId: 'customscript_app_customer', deployId: 'customdeploy_app_customer' });
 ```
 
-A type imported from another controller becomes an import of that controller's module. A type built on something the entity file imports itself (`CustomerCreate`, `CustomerPatch`: the repository package's input types) is an error, because the client could not carry it; write the wire shape out in the controller instead. A generated module no controller owns any more is deleted on the next run.
+A type imported from a service is copied the same way, with the entity types it is built on following it in from the models file. A type imported from another controller becomes an import of that controller's module. A type built on something no inlined file declares (`CustomerCreate`, `CustomerPatch`: the repository package's input types; a type a service imports from a package) is an error, because the client could not carry it; write the wire shape out in the controller instead. So is a type reached through a renamed import (`import type { Employee as EmployeeRecord }`) in a service: import it under its own name. A generated module no controller owns any more is deleted on the next run.
+
+JSON carries no dates. A `Date` in a response shape (an entity's `tranDate`) arrives in the browser as an ISO 8601 string, so the generated module writes `string` wherever the shape says `Date`; the page formats it. A `Date` in a request shape is an error, because the handler would receive a string where its annotation promises a Date: take a string and parse it in the handler.
 
 **`client/src/api/index.gen.ts`**, the client's view of the backend: every controller's module re-exported under the controller's name.
 
@@ -118,11 +120,11 @@ 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" }
+  "inlineTypes": { "../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 modules and the index, and nothing else. `inlineTypes` maps a specifier as written in a controller to the type-only file whose declarations are copied into the module of every controller importing from 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.
+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.
 
 ## The client at runtime
 
@@ -134,7 +136,7 @@ import { configureApiClient } from '@amerilux/netsuite-api/client';
 if (import.meta.env.DEV) configureApiClient({ basePaths: { restlet: '/api/restlet', suitelet: '/api/suitelet' } });
 ```
 
-A failed call rejects with an `ApiClientError` carrying the envelope's status and message; a call that got no answer at all carries `NO_RESPONSE_STATUS` (0). Before it rejects, the failure goes to the handler `configureApiClient` was given, with the script, the endpoint and the request, so the app reports every failure in one place and a hook carries no error handling of its own:
+A failed call rejects with an `ApiClientError` carrying the envelope's status, message and `details` (whatever the handler gave its `ApiError`, for a form to show per field); a call that got no answer at all carries `NO_RESPONSE_STATUS` (0). Before it rejects, the failure goes to the handler `configureApiClient` was given, with the script, the endpoint and the request, so the app reports every failure in one place and a hook carries no error handling of its own:
 
 ```ts
 configureApiClient({ onError: (error, { endpoint }) => showBanner(`${endpoint}: ${error.message}`) });

package/dist/client/apiClient.js

@@ -80,7 +80,7 @@ export function callEndpoint(scriptRef, endpointName, request = {}, options = {}
             throw new ApiClientError(response.status, `Unexpected response from ${scriptRef.scriptId} (${response.status})`, text.slice(0, 500));
         }
         if (envelope.error !== null || envelope.status >= 400) {
-            throw new ApiClientError(envelope.status, (_a = envelope.error) !== null && _a !== void 0 ? _a : `Request failed (${envelope.status})`);
+            throw new ApiClientError(envelope.status, (_a = envelope.error) !== null && _a !== void 0 ? _a : `Request failed (${envelope.status})`, envelope.details);
         }
         return envelope.data;
     });
@@ -99,7 +99,7 @@ export function callRawEndpoint(scriptRef, endpointName, request = {}, options =
             const text = await response.text();
             const envelope = parseEnvelope(text);
             if (envelope && (envelope.error !== null || envelope.status >= 400))
-                throw new ApiClientError(envelope.status, (_b = envelope.error) !== null && _b !== void 0 ? _b : `Request failed (${envelope.status})`);
+                throw new ApiClientError(envelope.status, (_b = envelope.error) !== null && _b !== void 0 ? _b : `Request failed (${envelope.status})`, envelope.details);
             if (!response.ok)
                 throw new ApiClientError(response.status, `Unexpected response from ${scriptRef.scriptId} (${response.status})`, text.slice(0, 500));
             throw new ApiClientError(response.status, `${scriptRef.scriptId}.${endpointName} answered JSON where a document was expected.`, text.slice(0, 500));

package/dist/index.d.ts

@@ -2,11 +2,16 @@
  * The wire: what a controller answers with, how a call names its endpoint, and how a script is
  * reached. Both sides import this module; nothing in it touches NetSuite or the browser.
  */
-/** Every controller answers with this envelope; `data` is null whenever `error` is set. */
+/**
+ * Every controller answers with this envelope; `data` is null whenever `error` is set. `details` is
+ * whatever the handler gave its ApiError (a per-field validation map, the offending id), sent so the
+ * caller can act on it; a 500 carries none, its cause stays in the log.
+ */
 export interface ApiEnvelope<TData> {
     status: number;
     error: string | null;
     data: TData | null;
+    details?: unknown;
 }
 /** The body of a failed call, as thrown by the client's ApiClientError. */
 export interface ApiErrorBody {

package/dist/server/endpoint.js

@@ -83,7 +83,7 @@ export function invokeEndpoint(controllerName, endpoints, rawRequest, options =
         if (error instanceof ApiError) {
             status = error.status;
             log.debug('endpoint rejected', { controller: controllerName, endpoint: endpointName, status, message: error.message, details: error.details });
-            return { envelope: { status, error: error.message, data: null } };
+            return { envelope: error.details === undefined ? { status, error: error.message, data: null } : { status, error: error.message, data: null, details: error.details } };
         }
         status = 500;
         log.error('endpoint failed', { controller: controllerName, endpoint: endpointName, ...describeError(error) });

package/dist/server/suiteletClient.js

@@ -35,7 +35,8 @@ export function callSuiteletEndpoint(scriptRef, endpointName, request = {}) {
     }
     const envelope = parseEnvelope(scriptRef, endpointName, response.body);
     if (envelope.error !== null || envelope.status >= 400) {
-        throw new ApiError(envelope.status, (_a = envelope.error) !== null && _a !== void 0 ? _a : `Request failed (${envelope.status})`, { script: scriptRef.scriptId, endpoint: endpointName });
+        // The called script's details travel on, so the caller (and through it the browser) can act on them.
+        throw new ApiError(envelope.status, (_a = envelope.error) !== null && _a !== void 0 ? _a : `Request failed (${envelope.status})`, envelope.details !== undefined ? envelope.details : { script: scriptRef.scriptId, endpoint: endpointName });
     }
     return envelope.data;
 }

package/dist-tooling/config.d.ts

@@ -22,10 +22,13 @@ export interface ClientGeneratorConfig {
      */
     typeImports: Record<string, string>;
     /**
-     * Type-only files whose declarations are copied into the generated module of every controller
-     * that imports from them, as the specifier written in the controller mapped to the file: the
-     * generated entity types. A controller module carries the types it names, and what those refer
-     * to, so the client needs no copy of the file.
+     * Files whose type declarations are copied into the generated module of every controller that
+     * imports types from them, as the specifier written in the controller mapped to the file: the
+     * generated entity types, and the services (a key with one `*` stands for a file name:
+     * `../services/*` mapped to `api/src/services/*.ts`). A controller module carries the types it
+     * names and what those refer to, following an import from one listed file into another, so the
+     * client needs no copy of any of them. Only the type declarations of a file are read; a service's
+     * functions are not.
      */
     inlineTypes: Record<string, string>;
 }
@@ -35,6 +38,11 @@ export interface ResolvedClientGeneratorConfig extends ClientGeneratorConfig {
 }
 export declare const DEFAULT_CONFIG_FILE_NAME = "netsuite-api.config.json";
 export declare const defaultClientGeneratorConfig: ClientGeneratorConfig;
+/**
+ * The file an inlineTypes entry names for a specifier: the exact key, or a key with one `*` standing
+ * for a single path segment, substituted into the value. Undefined when no entry matches.
+ */
+export declare function resolveInlineTypesFile(inlineTypes: Record<string, string>, specifier: string): string | undefined;
 export declare class ClientGeneratorConfigError extends Error {
     readonly configPath: string;
     readonly problems: string[];

package/dist-tooling/config.js

@@ -7,8 +7,31 @@ 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' },
+    inlineTypes: { '../types/models.gen': 'api/src/types/models.gen.ts', '../services/*': 'api/src/services/*.ts' },
 };
+const wildcardInlineTypesKeyPattern = /^([^*]*)\*([^*]*)$/;
+const wildcardSegmentPattern = /^[A-Za-z0-9_-]+$/;
+/**
+ * The file an inlineTypes entry names for a specifier: the exact key, or a key with one `*` standing
+ * for a single path segment, substituted into the value. Undefined when no entry matches.
+ */
+export function resolveInlineTypesFile(inlineTypes, specifier) {
+    const exact = inlineTypes[specifier];
+    if (exact !== undefined)
+        return exact;
+    for (const [key, filePattern] of Object.entries(inlineTypes)) {
+        const wildcard = wildcardInlineTypesKeyPattern.exec(key);
+        if (!wildcard)
+            continue;
+        const [, prefix, suffix] = wildcard;
+        if (specifier.length <= prefix.length + suffix.length || !specifier.startsWith(prefix) || !specifier.endsWith(suffix))
+            continue;
+        const segment = specifier.slice(prefix.length, specifier.length - suffix.length);
+        if (wildcardSegmentPattern.test(segment))
+            return filePattern.replace('*', segment);
+    }
+    return undefined;
+}
 export class ClientGeneratorConfigError extends Error {
     configPath;
     problems;
@@ -45,6 +68,15 @@ function validateClientGeneratorConfig(raw, configPath) {
         else
             problems.push(`'${setting}' must be an object of strings.`);
     }
+    for (const [key, filePattern] of Object.entries(config.inlineTypes)) {
+        const stars = (key.match(/\*/g) ?? []).length;
+        if (stars > 1)
+            problems.push(`'inlineTypes' key '${key}' has more than one '*'; one stands for the file name.`);
+        else if (stars === 1 && !filePattern.includes('*'))
+            problems.push(`'inlineTypes' key '${key}' has a '*' but its file '${filePattern}' has none to put the name in.`);
+        else if (stars === 0 && filePattern.includes('*'))
+            problems.push(`'inlineTypes' file '${filePattern}' has a '*' but its key '${key}' has none to take the name from.`);
+    }
     const known = new Set([...stringSettings, ...mapSettings]);
     for (const key of Object.keys(raw)) {
         if (!known.has(key))

package/dist-tooling/controllerReader.d.ts

@@ -4,8 +4,8 @@ import ts from 'typescript';
  * defineRestlet or defineSuitelet call, the exported types (the DTOs), and the name, request type and
  * response type of every endpoint in its `defineEndpoints({ ... })`. A parse, not a type check: the
  * handler annotations are the contract, so they must be written out, a DTO may only reference types
- * from the inlined files, the carried modules or another controller, and the script ids are string
- * literals.
+ * from the inlined files (the entity types, the services), the carried modules or another controller,
+ * and the script ids are string literals.
  */
 export interface ControllerProblem {
     filePath: string;

package/dist-tooling/controllerReader.js

@@ -1,5 +1,6 @@
 import * as nodePath from 'node:path';
 import ts from 'typescript';
+import { resolveInlineTypesFile } from './config.js';
 import { toPosixPath } from './file-system.js';
 /** The return type a handler writes, exactly, to answer with a document instead of the envelope. */
 export const RAW_RESPONSE_TYPE_NAME = 'RawResponse';
@@ -63,7 +64,7 @@ function readTypeImport(statement, filePath, options) {
     const sibling = siblingControllerSpecifierPattern.exec(moduleSpecifier);
     if (sibling)
         return { read: { kind: 'controller', typeImport: { controllerName: sibling[1], names } }, problems };
-    if (options.inlineTypes[moduleSpecifier] !== undefined)
+    if (resolveInlineTypesFile(options.inlineTypes, moduleSpecifier) !== undefined)
         return { read: { kind: 'inlined', typeImport: { specifier: moduleSpecifier, names } }, problems };
     const clientSpecifier = options.typeImports[moduleSpecifier];
     if (clientSpecifier !== undefined)

package/dist-tooling/emit.d.ts

@@ -1,8 +1,8 @@
 import type { ControllerContract, TypeDeclaration } from './controllerReader.js';
 /**
  * Writes the generated modules. Each controller gets its own client module, `<name>.gen.ts`: the
- * entity types it names (copied in, so the module stands on its own), its wire shapes, its endpoint
- * type and, when the browser calls it, its client. The index module re-exports each one as a
+ * entity and service types it names (copied in, so the module stands on its own), its wire shapes,
+ * its endpoint type and, when the browser calls it, its client. The index module re-exports each one as a
  * namespace, so a hook writes `user.api.roles()` and names a shape as `user.RolesResponse`. The
  * scripts module is the server-side map a repository passes to createSuiteletClient.
  */

package/dist-tooling/emit.js

@@ -1,4 +1,5 @@
 import { GENERATED_CLIENT_NAME, GENERATED_ENDPOINTS_TYPE_NAME } from './controllerReader.js';
+import { writeDatesAsStrings } from './wireTypes.js';
 /** The index module of the client, next to the controller modules: what a hook imports. */
 export const CLIENT_INDEX_FILE_NAME = 'index.gen.ts';
 /** The client module of a controller: `user.gen.ts` for the user controller. */
@@ -14,9 +15,10 @@ function indentJsDoc(jsDoc) {
         .map((line, index) => (index === 0 ? `${INDENT}${line.trim()}` : `${INDENT} ${line.trim()}`))
         .join('\n');
 }
+// A Date on the wire is an ISO string: the client module says so wherever a shape says Date.
 function emitEndpointMember(endpoint) {
-    const parameter = endpoint.requestType === undefined ? '' : `request${endpoint.requestOptional ? '?' : ''}: ${endpoint.requestType}`;
-    const member = `${INDENT}${endpoint.name}: (${parameter}) => ${endpoint.responseType};`;
+    const parameter = endpoint.requestType === undefined ? '' : `request${endpoint.requestOptional ? '?' : ''}: ${writeDatesAsStrings(endpoint.requestType, 'type')}`;
+    const member = `${INDENT}${endpoint.name}: (${parameter}) => ${writeDatesAsStrings(endpoint.responseType, 'type')};`;
     return endpoint.jsDoc ? `${indentJsDoc(endpoint.jsDoc)}\n${member}` : member;
 }
 function formatImportName(imported) {
@@ -55,12 +57,12 @@ export function emitControllerModule({ contract, sourceLabel, inlinedTypes }, op
     ];
     const sections = [header.join('\n'), imports.join('\n')];
     for (const section of inlinedTypes) {
-        sections.push(`// Entity types from ${section.sourceLabel}, copied so this module stands on its own.`);
+        sections.push(`// Types from ${section.sourceLabel}, copied so this module stands on its own.`);
         for (const declaration of section.declarations)
-            sections.push(declaration.text);
+            sections.push(writeDatesAsStrings(declaration.text, 'declaration'));
     }
     for (const declaration of contract.typeDeclarations)
-        sections.push(declaration.text);
+        sections.push(writeDatesAsStrings(declaration.text, 'declaration'));
     const members = contract.endpoints.map(emitEndpointMember);
     // A type alias, not an interface: only an object type literal satisfies the Endpoints index signature.
     sections.push(`/** The endpoint signatures of the ${contract.name} controller, as its handlers declare them. */\nexport type ${GENERATED_ENDPOINTS_TYPE_NAME} = {\n${members.join('\n')}\n};`);

package/dist-tooling/generate.js

@@ -1,8 +1,10 @@
 import * as nodePath from 'node:path';
+import { resolveInlineTypesFile } from './config.js';
 import { isControllerFileName, readControllerContract } from './controllerReader.js';
 import { CLIENT_INDEX_FILE_NAME, controllerModuleFileName, emitClientIndexModule, emitControllerModule, emitScriptsModule, sortControllers } from './emit.js';
 import { toPosixPath } from './file-system.js';
 import { readInlinableTypesFile, selectInlinedTypes } from './typesFileReader.js';
+import { readReferencedNames } from './wireTypes.js';
 const generatedFileNamePattern = /\.gen\.ts$/;
 function relativeLabel(rootDirectory, filePath) {
     return toPosixPath(nodePath.relative(rootDirectory, filePath));
@@ -22,6 +24,41 @@ function findDuplicateScriptIds(controllers) {
     }
     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) {
+    const declarations = new Map();
+    for (const declaration of contract.typeDeclarations)
+        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);
+    }
+    const problems = [];
+    for (const endpoint of contract.endpoints) {
+        if (endpoint.requestType === undefined)
+            continue;
+        const visited = new Set();
+        const pending = readReferencedNames(endpoint.requestType, 'type').map((name) => ({ name, via: endpoint.requestType }));
+        while (pending.length > 0) {
+            const { name, via } = pending.shift();
+            if (name === 'Date') {
+                problems.push({ filePath: controllerLabel, message: `endpoint '${endpoint.name}' takes a Date in its request (through ${via}); JSON carries dates as ISO 8601 strings, so take a string and parse it in the handler.` });
+                break;
+            }
+            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 problems;
+}
 /** Every generated file in the output directory that is not one of the given paths. */
 function findLeftoverFiles(fileSystem, outDirectory, plannedPaths) {
     const planned = new Set(plannedPaths.map((filePath) => toPosixPath(nodePath.resolve(filePath))));
@@ -41,15 +78,23 @@ export function planClientGeneration({ config, fileSystem }) {
     }
     const controllerNames = new Set(controllerFiles.map((filePath) => nodePath.basename(filePath).replace(/Controller\.ts$/, '')));
     const inlinableFiles = new Map();
+    /** The inlinable file a specifier names, read once; a file that does not exist is reported once and answered as 'missing'. */
     const readInlinable = (specifier) => {
-        if (inlinableFiles.has(specifier))
-            return inlinableFiles.get(specifier);
-        const filePath = resolve(config.inlineTypes[specifier]);
+        const known = inlinableFiles.get(specifier);
+        if (known !== undefined)
+            return known;
+        const relativePath = resolveInlineTypesFile(config.inlineTypes, specifier);
+        if (relativePath === undefined)
+            return undefined;
+        const filePath = resolve(relativePath);
         let file;
         if (fileSystem.fileExists(filePath))
             file = readInlinableTypesFile(label(filePath), fileSystem.readTextFile(filePath));
-        else
-            problems.push({ filePath: label(filePath), message: 'the file to copy types from does not exist; run the model generator first.' });
+        else {
+            file = 'missing';
+            const hint = config.inlineTypes[specifier] !== undefined ? 'run the model generator first.' : `'${specifier}' names it.`;
+            problems.push({ filePath: label(filePath), message: `the file to copy types from does not exist; ${hint}` });
+        }
         inlinableFiles.set(specifier, file);
         return file;
     };
@@ -72,16 +117,19 @@ export function planClientGeneration({ config, fileSystem }) {
         const inlinedTypes = [];
         for (const typeImport of contract.inlinedTypeImports) {
             const file = readInlinable(typeImport.specifier);
-            if (!file)
+            if (!file || file === 'missing')
                 continue;
-            const selected = selectInlinedTypes(file, typeImport.names, controllerLabel);
+            const selected = selectInlinedTypes(file, typeImport.names, controllerLabel, readInlinable);
             problems.push(...selected.problems);
-            const section = inlinedTypes.find((existing) => existing.sourceLabel === file.filePath);
-            if (section)
-                section.declarations.push(...selected.declarations.filter((declaration) => !section.declarations.some((existing) => existing.name === declaration.name)));
-            else
-                inlinedTypes.push({ sourceLabel: file.filePath, declarations: selected.declarations });
+            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 });
+            }
         }
+        problems.push(...findDatesInRequestShapes(contract, inlinedTypes, controllerLabel));
         emitted.push({ contract, sourceLabel: controllerLabel, inlinedTypes });
     }
     problems.push(...findDuplicateScriptIds(emitted));

package/dist-tooling/typesFileReader.d.ts

@@ -1,10 +1,12 @@
 import type { ControllerProblem, TypeDeclaration, TypeImportName } from './controllerReader.js';
 /**
- * Reads a type-only file whose declarations the generator copies into a controller's generated
- * module: the generated entity types. A controller names the types it imports from the file; each
- * of those is copied with every type it refers to in the same file, so the generated module stands
- * on its own. A type built on something the file imports (the repository package's EntityCreate and
- * EntityPatch) cannot be copied, because the client would need that package to resolve it.
+ * Reads a file whose type declarations the generator copies into a controller's generated module:
+ * the generated entity types, or a service (its functions are skipped; its types are what a
+ * controller builds wire shapes from). A controller names the types it imports from the file; each
+ * of those is copied with every type it refers to, in the same file or, through an import, in
+ * another inlinable file, so the generated module stands on its own. A type built on something no
+ * inlinable file declares (the repository package's EntityCreate and EntityPatch) cannot be copied,
+ * because the client would need that package to resolve it.
  */
 export interface InlinableTypeDeclaration extends TypeDeclaration {
     /** The names of the types the declaration refers to, each once, in the order met. */
@@ -17,15 +19,32 @@ export interface InlinableTypesFile {
     declarations: Map<string, InlinableTypeDeclaration>;
     /** Every name the file imports, mapped to the module it comes from. */
     importedNames: Map<string, string>;
+    /** The imports written `Name as Local`: the local name mapped to the name the module exports. */
+    renamedImports: Map<string, string>;
 }
-export interface SelectedInlinedTypes {
-    /** The declarations to copy, in file order, followed by an alias for every renamed import. */
+/** The declarations to copy from one file. */
+export interface SelectedInlinedSection {
+    filePath: string;
+    /** In file order; the section of the file the controller named ends with an alias for every renamed import. */
     declarations: TypeDeclaration[];
+}
+export interface SelectedInlinedTypes {
+    /** One section per file the selection reached, the file the controller named first. */
+    sections: SelectedInlinedSection[];
     problems: ControllerProblem[];
 }
+/**
+ * Resolves a specifier written in an inlinable file to the inlinable file it names: undefined when
+ * the client could not carry it, 'missing' when it names an inlinable file that does not exist (the
+ * resolver reports that itself).
+ */
+export type ResolveInlinableImport = (specifier: string) => InlinableTypesFile | 'missing' | undefined;
 export declare function readInlinableTypesFile(filePath: string, source: string): InlinableTypesFile;
 /**
  * The declarations a controller's imports pull out of the file: the named types and, transitively,
- * what they refer to. A name the file does not declare is a problem reported against the controller.
+ * what they refer to. A reference to a name the file imports is followed into the inlinable file the
+ * import resolves to, so a service's summary type built on an entity type carries the entity type
+ * with it. A name the file does not declare, or an import the client could not carry, is a problem
+ * reported against the controller.
  */
-export declare function selectInlinedTypes(file: InlinableTypesFile, names: TypeImportName[], controllerPath: string): SelectedInlinedTypes;
+export declare function selectInlinedTypes(file: InlinableTypesFile, names: TypeImportName[], controllerPath: string, resolveImport?: ResolveInlinableImport): SelectedInlinedTypes;

package/dist-tooling/typesFileReader.js

@@ -1,21 +1,7 @@
 import ts from 'typescript';
 import { readLeadingJsDoc } from './controllerReader.js';
-function leftmostIdentifier(name) {
-    return ts.isIdentifier(name) ? name.text : leftmostIdentifier(name.left);
-}
-function collectTypeReferences(node, references) {
-    let referenced;
-    if (ts.isTypeReferenceNode(node))
-        referenced = leftmostIdentifier(node.typeName);
-    else if (ts.isTypeQueryNode(node))
-        referenced = leftmostIdentifier(node.exprName);
-    else if (ts.isExpressionWithTypeArguments(node) && ts.isIdentifier(node.expression))
-        referenced = node.expression.text;
-    if (referenced !== undefined && !references.includes(referenced))
-        references.push(referenced);
-    ts.forEachChild(node, (child) => collectTypeReferences(child, references));
-}
-function readImportedNames(statement, importedNames) {
+import { collectTypeReferences } from './wireTypes.js';
+function readImportedNames(statement, importedNames, renamedImports) {
     const clause = statement.importClause;
     if (!clause || !ts.isStringLiteral(statement.moduleSpecifier))
         return;
@@ -27,17 +13,22 @@ function readImportedNames(statement, importedNames) {
         return;
     if (ts.isNamespaceImport(bindings))
         importedNames.set(bindings.name.text, moduleSpecifier);
-    else
-        for (const element of bindings.elements)
+    else {
+        for (const element of bindings.elements) {
             importedNames.set(element.name.text, moduleSpecifier);
+            if (element.propertyName)
+                renamedImports.set(element.name.text, element.propertyName.text);
+        }
+    }
 }
 export function readInlinableTypesFile(filePath, source) {
     const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
     const declarations = new Map();
     const importedNames = new Map();
+    const renamedImports = new Map();
     for (const statement of sourceFile.statements) {
         if (ts.isImportDeclaration(statement)) {
-            readImportedNames(statement, importedNames);
+            readImportedNames(statement, importedNames, renamedImports);
             continue;
         }
         if (!ts.isInterfaceDeclaration(statement) && !ts.isTypeAliasDeclaration(statement) && !ts.isEnumDeclaration(statement))
@@ -52,46 +43,87 @@ export function readInlinableTypesFile(filePath, source) {
         const jsDoc = readLeadingJsDoc(statement, sourceFile);
         declarations.set(statement.name.text, { name: statement.name.text, text: `${jsDoc ? `${jsDoc}\n` : ''}${statement.getText(sourceFile)}`, references });
     }
-    return { filePath, declarations, importedNames };
+    return { filePath, declarations, importedNames, renamedImports };
 }
 /**
  * The declarations a controller's imports pull out of the file: the named types and, transitively,
- * what they refer to. A name the file does not declare is a problem reported against the controller.
+ * what they refer to. A reference to a name the file imports is followed into the inlinable file the
+ * import resolves to, so a service's summary type built on an entity type carries the entity type
+ * with it. A name the file does not declare, or an import the client could not carry, is a problem
+ * reported against the controller.
  */
-export function selectInlinedTypes(file, names, controllerPath) {
+export function selectInlinedTypes(file, names, controllerPath, resolveImport = () => undefined) {
     const problems = [];
-    const selected = new Set();
-    const pending = names.map((imported) => ({ name: imported.name }));
+    const reached = new Map([[file.filePath, file]]);
+    const selectedByFile = new Map();
+    const selectedIn = (current) => {
+        let selected = selectedByFile.get(current.filePath);
+        if (!selected) {
+            selected = new Set();
+            selectedByFile.set(current.filePath, selected);
+        }
+        return selected;
+    };
+    const pending = names.map((imported) => ({ file, name: imported.name }));
     while (pending.length > 0) {
-        const { name, dependent } = pending.shift();
+        const { file: current, name, dependent } = pending.shift();
+        const selected = selectedIn(current);
         if (selected.has(name))
             continue;
-        const declaration = file.declarations.get(name);
+        const declaration = current.declarations.get(name);
         if (declaration) {
             selected.add(name);
-            pending.push(...declaration.references.map((reference) => ({ name: reference, dependent: name })));
+            pending.push(...declaration.references.map((reference) => ({ file: current, name: reference, dependent: name })));
             continue;
         }
-        const importedFrom = file.importedNames.get(name);
+        const importedFrom = current.importedNames.get(name);
         if (importedFrom !== undefined) {
-            problems.push({
-                filePath: controllerPath,
-                message: dependent
-                    ? `type '${dependent}' (${file.filePath}) is built on ${name} from '${importedFrom}', which the client cannot carry; write the wire shape out in the controller instead.`
-                    : `type '${name}' is imported into ${file.filePath} from '${importedFrom}', not declared there; the client cannot carry it.`,
-            });
+            const imported = resolveImport(importedFrom);
+            const exportedName = current.renamedImports.get(name);
+            if (imported === 'missing') {
+                // The resolver reported the missing file; the reference has nothing to say beyond that.
+            }
+            else if (imported && exportedName === undefined) {
+                if (!reached.has(imported.filePath))
+                    reached.set(imported.filePath, imported);
+                selected.add(name);
+                pending.push({ file: imported, name, dependent });
+            }
+            else if (imported) {
+                problems.push({
+                    filePath: controllerPath,
+                    message: dependent
+                        ? `type '${dependent}' (${current.filePath}) is built on ${name}, imported from '${importedFrom}' as a rename of ${exportedName}; import it under its own name so the client can carry it.`
+                        : `type '${name}' is imported into ${current.filePath} from '${importedFrom}' as a rename of ${exportedName}; import it under its own name so the client can carry it.`,
+                });
+            }
+            else {
+                problems.push({
+                    filePath: controllerPath,
+                    message: dependent
+                        ? `type '${dependent}' (${current.filePath}) is built on ${name} from '${importedFrom}', which the client cannot carry; write the wire shape out in the controller instead.`
+                        : `type '${name}' is imported into ${current.filePath} from '${importedFrom}', not declared there; the client cannot carry it.`,
+                });
+            }
         }
         else if (dependent === undefined) {
-            problems.push({ filePath: controllerPath, message: `type '${name}' is not declared in ${file.filePath}.` });
+            problems.push({ filePath: controllerPath, message: `type '${name}' is not declared in ${current.filePath}.` });
         }
         // Anything else a declaration refers to is a global (Date, Record, Array): nothing to copy.
     }
-    const declarations = Array.from(file.declarations.values())
-        .filter((declaration) => selected.has(declaration.name))
-        .map(({ name, text }) => ({ name, text }));
+    const sections = Array.from(reached.values()).map((current) => {
+        const selected = selectedByFile.get(current.filePath);
+        return {
+            filePath: current.filePath,
+            declarations: Array.from(current.declarations.values())
+                .filter((declaration) => selected?.has(declaration.name))
+                .map(({ name, text }) => ({ name, text })),
+        };
+    });
+    const resolvedNames = new Set(sections.flatMap((section) => section.declarations.map((declaration) => declaration.name)));
     for (const imported of names) {
-        if (imported.alias && selected.has(imported.name))
-            declarations.push({ name: imported.alias, text: `export type ${imported.alias} = ${imported.name};` });
+        if (imported.alias && resolvedNames.has(imported.name))
+            sections[0].declarations.push({ name: imported.alias, text: `export type ${imported.alias} = ${imported.name};` });
     }
-    return { declarations, problems };
+    return { sections: sections.filter((section, index) => index === 0 || section.declarations.length > 0), problems };
 }

package/dist-tooling/wireTypes.d.ts

@@ -0,0 +1,16 @@
+import ts from 'typescript';
+/**
+ * JSON carries no dates: a Date on the wire is an ISO 8601 string in both directions, and neither
+ * side revives it. So the generated client module says `string` wherever a wire shape says `Date`,
+ * and a request shape may not carry a Date at all, because the handler would receive a string where
+ * its annotation promises a Date. The shapes are text (the declarations as written, the handler
+ * annotations), so both operations parse the text and work on the syntax tree.
+ */
+/** A fragment is a whole declaration (`export interface X { ... }`) or a bare type annotation (`Date[]`). */
+export type WireFragmentKind = 'declaration' | 'type';
+/** Collects, in order met and each once, the names a node refers to: type references, heritage clauses and typeof targets. */
+export declare function collectTypeReferences(node: ts.Node, references: string[]): void;
+/** The names a fragment refers to, `Date` included when it does. */
+export declare function readReferencedNames(text: string, kind: WireFragmentKind): string[];
+/** The fragment with every `Date` type reference written as `string`, everything else byte for byte as it was. */
+export declare function writeDatesAsStrings(text: string, kind: WireFragmentKind): string;

package/dist-tooling/wireTypes.js

@@ -0,0 +1,50 @@
+import ts from 'typescript';
+const TYPE_FRAGMENT_PREFIX = 'type __WireFragment = ';
+function parseFragment(text, kind) {
+    const source = kind === 'type' ? `${TYPE_FRAGMENT_PREFIX}${text};` : text;
+    return { sourceFile: ts.createSourceFile('wire.ts', source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS), offset: kind === 'type' ? TYPE_FRAGMENT_PREFIX.length : 0 };
+}
+function leftmostIdentifier(name) {
+    return ts.isIdentifier(name) ? name.text : leftmostIdentifier(name.left);
+}
+/** Collects, in order met and each once, the names a node refers to: type references, heritage clauses and typeof targets. */
+export function collectTypeReferences(node, references) {
+    let referenced;
+    if (ts.isTypeReferenceNode(node))
+        referenced = leftmostIdentifier(node.typeName);
+    else if (ts.isTypeQueryNode(node))
+        referenced = leftmostIdentifier(node.exprName);
+    else if (ts.isExpressionWithTypeArguments(node) && ts.isIdentifier(node.expression))
+        referenced = node.expression.text;
+    if (referenced !== undefined && !references.includes(referenced))
+        references.push(referenced);
+    ts.forEachChild(node, (child) => collectTypeReferences(child, references));
+}
+/** The names a fragment refers to, `Date` included when it does. */
+export function readReferencedNames(text, kind) {
+    const { sourceFile } = parseFragment(text, kind);
+    const references = [];
+    collectTypeReferences(sourceFile, references);
+    return references.filter((name) => name !== '__WireFragment');
+}
+function isDateReference(node) {
+    return ts.isTypeReferenceNode(node) && ts.isIdentifier(node.typeName) && node.typeName.text === 'Date' && node.typeArguments === undefined;
+}
+function collectNodes(node, matches, found) {
+    if (matches(node))
+        found.push(node);
+    ts.forEachChild(node, (child) => collectNodes(child, matches, found));
+}
+/** The fragment with every `Date` type reference written as `string`, everything else byte for byte as it was. */
+export function writeDatesAsStrings(text, kind) {
+    const { sourceFile, offset } = parseFragment(text, kind);
+    const references = [];
+    collectNodes(sourceFile, isDateReference, references);
+    let result = text;
+    for (const reference of references.sort((left, right) => right.getStart(sourceFile) - left.getStart(sourceFile))) {
+        const start = reference.getStart(sourceFile) - offset;
+        const end = reference.getEnd() - offset;
+        result = `${result.slice(0, start)}string${result.slice(end)}`;
+    }
+    return result;
+}

package/package.json

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