@amerilux/netsuite-api 0.2.1 → 0.5.0

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.5.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",