@travetto/transformer 6.0.0 → 7.0.0-rc.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/transformer",
-  "version": "6.0.0",
+  "version": "7.0.0-rc.0",
   "description": "Functionality for AST transformations, with transformer registration, and general utils",
   "keywords": [
     "typescript",
@@ -24,9 +24,9 @@
     "directory": "module/transformer"
   },
   "dependencies": {
-    "@travetto/manifest": "^6.0.0",
+    "@travetto/manifest": "^7.0.0-rc.0",
     "tslib": "^2.8.1",
-    "typescript": "^5.8.3"
+    "typescript": "^5.9.3"
   },
   "travetto": {
     "displayName": "Transformation",

package/src/importer.ts

@@ -2,7 +2,7 @@ import ts from 'typescript';
 
 import { ManifestModuleUtil, PackageUtil, path } from '@travetto/manifest';
 
-import { AnyType, TransformResolver, ManagedType } from './resolver/types.ts';
+import { AnyType, TransformResolver, ManagedType, MappedType } from './resolver/types.ts';
 import { ImportUtil } from './util/import.ts';
 import { CoreUtil } from './util/core.ts';
 import { Import } from './types/shared.ts';
@@ -246,12 +246,14 @@ export class ImportManager {
   /**
    * Get the identifier and import if needed
    */
-  getOrImport(factory: ts.NodeFactory, type: ManagedType): ts.Identifier | ts.PropertyAccessExpression {
+  getOrImport(factory: ts.NodeFactory, type: ManagedType | MappedType): ts.Identifier | ts.PropertyAccessExpression {
+    const targetName = type.key === 'managed' ? type.name! : type.mappedClassName!;
+    // In same file already
     if (type.importName === this.#importName) {
-      return factory.createIdentifier(type.name!);
+      return factory.createIdentifier(targetName);
     } else {
       const { ident } = this.#imports.get(type.importName) ?? this.importFile(type.importName);
-      return factory.createPropertyAccessExpression(ident, type.name!);
+      return factory.createPropertyAccessExpression(ident, targetName);
     }
   }
 }

package/src/register.ts

@@ -115,6 +115,15 @@ export function OnMethod(...target: string[]) {
   ): void => storeHandler(inst, d.value!, 'before', 'method', target);
 }
 
+/**
+ * Listens for a `ts.ConstructorDeclaration`, on descent
+ */
+export function OnConstructor(...target: string[]) {
+  return <S extends State = State, R extends ts.Node = ts.Node>(
+    inst: Transformer, __: unknown, d: TypedPropertyDescriptor<(state: S, node: ts.ConstructorDeclaration, dm?: DecoratorMeta) => R>
+  ): void => storeHandler(inst, d.value!, 'before', 'constructor', target);
+}
+
 /**
  * Listens for a static `ts.MethodDeclaration`, on descent
  */
@@ -214,6 +223,15 @@ export function AfterMethod(...target: string[]) {
   ): void => storeHandler(inst, d.value!, 'after', 'method', target);
 }
 
+/**
+ * Listens for a `ts.ConstructorDeclaration`, on ascent
+ */
+export function AfterConstructor(...target: string[]) {
+  return <S extends State = State, R extends ts.Node = ts.Node>(
+    inst: Transformer, __: unknown, d: TypedPropertyDescriptor<(state: S, node: ts.ConstructorDeclaration, dm?: DecoratorMeta) => R>
+  ): void => storeHandler(inst, d.value!, 'after', 'constructor', target);
+}
+
 /**
  * Listens for a static `ts.MethodDeclaration`, on ascent
  */

package/src/resolver/builder.ts

@@ -9,11 +9,13 @@ import { DeclarationUtil } from '../util/declaration.ts';
 import { LiteralUtil } from '../util/literal.ts';
 import { transformCast, TemplateLiteralPart } from '../types/shared.ts';
 
-import { Type, AnyType, CompositionType, TransformResolver, TemplateType } from './types.ts';
+import { Type, AnyType, CompositionType, TransformResolver, TemplateType, MappedType } from './types.ts';
 import { CoerceUtil } from './coerce.ts';
 
 const UNDEFINED = Symbol();
 
+const MAPPED_TYPE_SET = new Set(['Omit', 'Pick', 'Required', 'Partial']);
+const isMappedType = (type: string | undefined): type is MappedType['operation'] => MAPPED_TYPE_SET.has(type!);
 /**
  * List of global types that can be parameterized
  */
@@ -39,7 +41,7 @@ const GLOBAL_SIMPLE: Record<string, Function> = {
 
 type Category =
   'tuple' | 'shape' | 'literal' | 'template' | 'managed' |
-  'composition' | 'foreign' | 'concrete' | 'unknown';
+  'composition' | 'foreign' | 'concrete' | 'unknown' | 'mapped';
 
 /**
  * Type categorizer, input for builder
@@ -102,9 +104,9 @@ export function TypeCategorize(resolver: TransformResolver, type: ts.Type): { ca
     return { category: 'tuple', type };
   } else if (type.isLiteral()) {
     return { category: 'shape', type };
-  } else if ((objectFlags & ts.ObjectFlags.Mapped)) { // Mapped types: Pick, Omit, Exclude, Retain
+  } else if (objectFlags & ts.ObjectFlags.Mapped) { // Mapped types
     if (type.getProperties().some(x => x.declarations || x.valueDeclaration)) {
-      return { category: 'shape', type };
+      return { category: 'mapped', type };
     }
   }
   return { category: 'literal', type };
@@ -249,6 +251,45 @@ export const TypeBuilder: {
       return type;
     }
   },
+  mapped: {
+    build: (resolver, type, alias) => {
+      let mainType: ts.Type | undefined;
+      let fields: string[] | undefined;
+      let operation: string | undefined;
+
+      const decls = DeclarationUtil.getDeclarations(type).filter(x => ts.isTypeAliasDeclaration(x));
+      if (decls.length > 0) {
+        const ref = decls[0].type;
+        if (ts.isTypeReferenceNode(ref) && ref.typeArguments && ref.typeArguments.length > 0) {
+          const [first, second] = ref.typeArguments;
+          mainType = resolver.getType(first);
+          operation = ref.typeName.getText();
+          if (second) {
+            const resolved = resolver.getType(second);
+            if (resolved.isStringLiteral()) {
+              fields = [resolved.value];
+            } else if (resolved.isUnion() && resolved.types.every(t => t.isStringLiteral())) {
+              fields = resolved.types.map(t => t.value);
+            }
+          }
+        }
+      } else {
+        mainType = type.aliasTypeArguments?.[0]!;
+        operation = type.aliasSymbol?.escapedName.toString();
+        fields = type.getApparentProperties().map(p => p.getName());
+      }
+
+      if (!isMappedType(operation) || fields === undefined || !mainType || !mainType.isClass()) {
+        return TypeBuilder.shape.build(resolver, type, alias);
+      }
+
+      const importName = resolver.getTypeImportName(mainType) ?? '<unknown>';
+      const mappedClassName = resolver.getTypeAsString(mainType)!;
+      const name = resolver.getTypeAsString(type)!;
+
+      return { key: 'mapped', name, original: mainType, operation, importName, mappedClassName, fields };
+    }
+  },
   shape: {
     build: (resolver, type, alias?) => {
       const tsFieldTypes: Record<string, ts.Type> = {};

package/src/resolver/service.ts

@@ -59,7 +59,7 @@ export class SimpleResolver implements TransformResolver {
    * Resolve an import name (e.g. @module/path/file) for a type
    */
   getTypeImportName(type: ts.Type, removeExt?: boolean): string | undefined {
-    const ogSource = DeclarationUtil.getPrimaryDeclarationNode(type)?.getSourceFile()?.fileName;
+    const ogSource = DeclarationUtil.getOptionalPrimaryDeclarationNode(type)?.getSourceFile()?.fileName;
     return ogSource ? this.getFileImportName(ogSource, removeExt) : undefined;
   }
 
@@ -106,7 +106,7 @@ export class SimpleResolver implements TransformResolver {
    * Get list of properties
    */
   getPropertiesOfType(type: ts.Type): ts.Symbol[] {
-    return this.#tsChecker.getPropertiesOfType(type);
+    return this.#tsChecker.getPropertiesOfType(type).filter(x => x.getName() !== '__proto__' && x.getName() !== 'prototype');
   }
 
   /**
@@ -117,7 +117,7 @@ export class SimpleResolver implements TransformResolver {
     const resolve = (resType: ts.Type, alias?: ts.Symbol, depth = 0): AnyType => {
 
       if (depth > 20) { // Max depth is 20
-        throw new Error('Object structure too nested');
+        throw new Error(`Object structure too nested: ${'getText' in node ? node.getText() : ''}`);
       }
 
       const { category, type } = TypeCategorize(this, resType);
@@ -131,7 +131,9 @@ export class SimpleResolver implements TransformResolver {
       // Recurse
       if (result) {
         result.original = resType;
-        result.comment = DocUtil.describeDocs(type).description;
+        try {
+          result.comment = DocUtil.describeDocs(type).description;
+        } catch { }
 
         if ('tsTypeArguments' in result) {
           result.typeArguments = result.tsTypeArguments!.map((elType) => resolve(elType, type.aliasSymbol, depth + 1));

package/src/resolver/types.ts

@@ -61,23 +61,42 @@ export interface ShapeType extends Type<'shape'> {
    * Does not include methods, used for shapes not concrete types
    */
   fieldTypes: Record<string, AnyType>;
-
   /**
    * Type Info
    */
   tsFieldTypes?: Record<string, ts.Type>;
-
   /**
    * Type arguments
    */
   typeArguments?: AnyType[];
-
   /**
    * Type Arguments
    */
   tsTypeArguments?: ts.Type[];
 }
 
+/**
+ * A type that is mapped
+ */
+export interface MappedType extends Type<'mapped'> {
+  /**
+   *  Location the type came from, for class references
+   */
+  importName: string;
+  /**
+   * Mapped class name
+   */
+  mappedClassName: string;
+  /**
+   * The type of mapping operation
+   */
+  operation: 'Omit' | 'Pick' | 'Partial' | 'Required';
+  /**
+   * The fields being provided for the mapping
+   */
+  fields: string[];
+}
+
 /**
  * A literal type, with an optional real value
  */
@@ -168,7 +187,6 @@ export interface ForeignType extends Type<'foreign'> {
    * Identifier for type
    */
   name: string;
-
   /**
    * Primary source file
    */
@@ -181,7 +199,7 @@ export interface ForeignType extends Type<'foreign'> {
 export interface UnknownType extends Type<'unknown'> { }
 
 export type AnyType =
-  TupleType | ShapeType | CompositionType | LiteralType |
+  TupleType | ShapeType | CompositionType | LiteralType | MappedType |
   ManagedType | PointerType | UnknownType | ForeignType | TemplateType;
 
 /**

package/src/state.ts

@@ -2,7 +2,7 @@ import ts from 'typescript';
 
 import { path, ManifestIndex } from '@travetto/manifest';
 
-import { ManagedType, AnyType, ForeignType } from './resolver/types.ts';
+import { ManagedType, AnyType, ForeignType, MappedType } from './resolver/types.ts';
 import { State, DecoratorMeta, Transformer, ModuleNameSymbol } from './types/visitor.ts';
 import { SimpleResolver } from './resolver/service.ts';
 import { ImportManager } from './importer.ts';
@@ -64,7 +64,7 @@ export class TransformerState implements State {
   /**
    * Get or import the node or external type
    */
-  getOrImport(type: ManagedType): ts.Identifier | ts.PropertyAccessExpression {
+  getOrImport(type: ManagedType | MappedType): ts.Identifier | ts.PropertyAccessExpression {
     return this.#imports.getOrImport(this.factory, type);
   }
 
@@ -129,6 +129,16 @@ export class TransformerState implements State {
     return DocUtil.readDocTag(this.#resolver.getType(node), name);
   }
 
+  /**
+   * Read all JSDoc tags as a list, with split support
+   */
+  readDocTagList(node: ts.Declaration, name: string): string[] {
+    return this.readDocTag(node, name)
+      .flatMap(x => x.split(/\s*,\s*/g))
+      .map(x => x.replace(/`/g, ''))
+      .filter(x => !!x);
+  }
+
   /**
    * Import a decorator, generally to handle erasure
    */
@@ -154,20 +164,20 @@ export class TransformerState implements State {
    */
   getDecoratorMeta(dec: ts.Decorator): DecoratorMeta | undefined {
     const ident = DecoratorUtil.getDecoratorIdent(dec);
-    const decl = DeclarationUtil.getPrimaryDeclarationNode(
-      this.#resolver.getType(ident)
-    );
+    const type = this.#resolver.getType(ident);
+    const decl = DeclarationUtil.getOptionalPrimaryDeclarationNode(type);
     const src = decl?.getSourceFile().fileName;
     const mod = src ? this.#resolver.getFileImportName(src, true) : undefined;
     const file = this.#manifestIndex.getFromImport(mod ?? '')?.outputFile;
-    const targets = DocUtil.readAugments(this.#resolver.getType(ident));
+    const targets = DocUtil.readAugments(type);
+    const example = DocUtil.readExample(type);
     const module = file ? mod : undefined;
     const name = ident ?
       ident.escapedText?.toString()! :
       undefined;
 
     if (ident && name) {
-      return { dec, ident, file, module, targets, name };
+      return { dec, ident, file, module, targets, name, options: example };
     }
   }
 
@@ -392,9 +402,15 @@ export class TransformerState implements State {
    * Produce a foreign target type
    */
   getForeignTarget(ret: ForeignType): ts.Expression {
-    return this.fromLiteral({
-      Ⲑid: `${ret.source.split('node_modules/')[1]}+${ret.name}`
-    });
+    return this.factory.createClassExpression([], undefined, undefined, undefined, [
+      this.factory.createPropertyDeclaration(
+        [this.factory.createModifier(ts.SyntaxKind.StaticKeyword)],
+        'Ⲑid',
+        undefined,
+        undefined,
+        this.fromLiteral(`${ret.source.split('node_modules/')[1]}+${ret.name}`)
+      )
+    ]);
   }
 
   /**

package/src/types/visitor.ts

@@ -10,6 +10,7 @@ export type DecoratorMeta = {
   file?: string;
   targets?: string[];
   name?: string;
+  options?: string[];
 };
 
 export type State = {
@@ -23,8 +24,9 @@ export type State = {
 export type TransformPhase = 'before' | 'after';
 
 export type TransformerType =
-  'class' | 'method' | 'property' | 'getter' | 'setter' | 'parameter' |
-  'static-method' | 'call' | 'function' | 'file' | 'type' | 'interface';
+  'class' | 'method' | 'property' | 'getter' | 'setter' | 'parameter'
+  | 'static-method' | 'call' | 'function' | 'file' | 'type' | 'interface'
+  | 'constructor';
 
 export const ModuleNameSymbol = Symbol.for('@travetto/transformer:id');
 

package/src/util/declaration.ts

@@ -1,6 +1,8 @@
 import ts from 'typescript';
 import { CoreUtil } from './core.ts';
 
+const isNamed = (o: ts.Declaration): o is ts.Declaration & { name: ts.Node } => 'name' in o && !!o.name;
+
 /**
  * Declaration utils
  */
@@ -23,7 +25,8 @@ export class DeclarationUtil {
    */
   static isPublic(node: ts.Declaration): boolean {
     // eslint-disable-next-line no-bitwise
-    return !(ts.getCombinedModifierFlags(node) & ts.ModifierFlags.NonPublicAccessibilityModifier);
+    return !(ts.getCombinedModifierFlags(node) & ts.ModifierFlags.NonPublicAccessibilityModifier) &&
+      (!isNamed(node) || !ts.isPrivateIdentifier(node.name));
   }
 
   /**
@@ -42,15 +45,19 @@ export class DeclarationUtil {
   /**
    * Find primary declaration out of a list of declarations
    */
-  static getPrimaryDeclaration(decls: ts.Declaration[]): ts.Declaration {
-    return decls?.[0];
+  static getPrimaryDeclarationNode(node: ts.Type | ts.Symbol): ts.Declaration {
+    const decls = this.getDeclarations(node);
+    if (!decls.length) {
+      throw new Error('No declarations found for type');
+    }
+    return decls[0];
   }
 
   /**
    * Find primary declaration out of a list of declarations
    */
-  static getPrimaryDeclarationNode(node: ts.Type | ts.Symbol): ts.Declaration {
-    return this.getPrimaryDeclaration(this.getDeclarations(node));
+  static getOptionalPrimaryDeclarationNode(node: ts.Type | ts.Symbol): ts.Declaration | undefined {
+    return this.getDeclarations(node)[0];
   }
 
   /**
@@ -88,4 +95,11 @@ export class DeclarationUtil {
     }
     return acc;
   }
+
+  static isStatic(node: ts.Declaration): boolean {
+    if ('modifiers' in node && Array.isArray(node.modifiers)) {
+      return node.modifiers?.some(x => x.kind === ts.SyntaxKind.StaticKeyword) ?? false;
+    }
+    return false;
+  }
 }

package/src/util/doc.ts

@@ -26,25 +26,25 @@ export class DocUtil {
    * Read JS Docs from a `ts.Declaration`
    */
   static describeDocs(node: ts.Declaration | ts.Type): DeclDocumentation {
-    if (node && !('getSourceFile' in node)) {
-      node = DeclarationUtil.getPrimaryDeclarationNode(node);
-    }
+    let toDescribe = (node && !('getSourceFile' in node)) ?
+      DeclarationUtil.getOptionalPrimaryDeclarationNode(node) : node;
+
     const out: DeclDocumentation = {
       description: undefined,
       return: undefined,
       params: []
     };
 
-    if (node) {
-      const tags = ts.getJSDocTags(node);
-      while (!this.hasJSDoc(node) && CoreUtil.hasOriginal(node)) {
-        node = transformCast<ts.Declaration>(node.original);
+    if (toDescribe) {
+      const tags = ts.getJSDocTags(toDescribe);
+      while (!this.hasJSDoc(toDescribe) && CoreUtil.hasOriginal(toDescribe)) {
+        toDescribe = transformCast<ts.Declaration>(toDescribe.original);
       }
 
-      const docs = this.hasJSDoc(node) ? node.jsDoc : undefined;
+      const docs = this.hasJSDoc(toDescribe) ? toDescribe.jsDoc : undefined;
 
       if (docs) {
-        const top = docs[docs.length - 1];
+        const top = docs.at(-1)!;
         if (ts.isJSDoc(top)) {
           out.description = this.getDocComment(top, out.description);
         }
@@ -92,4 +92,12 @@ export class DocUtil {
   static readAugments(type: ts.Type | ts.Symbol): string[] {
     return this.readDocTag(type, 'augments').map(x => x.replace(/^.*?([^` ]+).*?$/, (_, b) => b));
   }
+
+  /**
+   * Read example information
+   * @param type
+   */
+  static readExample(type: ts.Type | ts.Symbol): string[] {
+    return this.readDocTag(type, 'example').map(x => x.replace(/^.*?([^` ]+).*?$/, (_, b) => b));
+  }
 }

package/src/util/log.ts

@@ -38,7 +38,7 @@ export class LogUtil {
       const ox = x;
       const out: Record<string, unknown> = {};
       for (const key of TypedObject.keys(ox)) {
-        if (Object.getPrototypeOf(ox[key]) === Function.prototype || exclude.has(key) || ox[key] === undefined) {
+        if (ox[key] === null || ox[key] === undefined || Object.getPrototypeOf(ox[key]) === Function.prototype || exclude.has(key)) {
           continue;
         }
         try {

package/src/visitor.ts

@@ -16,7 +16,9 @@ export class VisitorFactory<S extends State = State> {
    * Get the type of transformer from a given a ts.node
    */
   static nodeToType(node: ts.Node): TransformerType | undefined {
-    if (ts.isMethodDeclaration(node)) {
+    if (ts.isConstructorDeclaration(node)) {
+      return 'constructor';
+    } else if (ts.isMethodDeclaration(node)) {
       // eslint-disable-next-line no-bitwise
       return (ts.getCombinedModifierFlags(node) & ts.ModifierFlags.Static) ? 'static-method' : 'method';
     } else if (ts.isPropertyDeclaration(node)) {