@travetto/transformer 8.0.0-alpha.1 → 8.0.0-alpha.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/transformer",
-  "version": "8.0.0-alpha.1",
+  "version": "8.0.0-alpha.11",
   "type": "module",
   "description": "Functionality for AST transformations, with transformer registration, and general utils",
   "keywords": [
@@ -25,9 +25,9 @@
     "directory": "module/transformer"
   },
   "dependencies": {
-    "@travetto/manifest": "^8.0.0-alpha.1",
+    "@travetto/manifest": "^8.0.0-alpha.8",
     "tslib": "^2.8.1",
-    "typescript": "^6.0.1-rc"
+    "typescript": "^6.0.3"
   },
   "travetto": {
     "displayName": "Transformation",

package/src/resolver/builder.ts

@@ -9,12 +9,13 @@ import { DeclarationUtil } from '../util/declaration.ts';
 import { LiteralUtil } from '../util/literal.ts';
 import { transformCast, type TemplateLiteralPart } from '../types/shared.ts';
 
-import type { Type, AnyType, CompositionType, TransformResolver, TemplateType, MappedType } from './types.ts';
+import type { Type, AnyType, CompositionType, TransformResolver, TemplateType, MappedType, ShapeType, ResolverContext, ManagedType } from './types.ts';
 import { CoerceUtil } from './coerce.ts';
 
 const UNDEFINED = Symbol();
 
 const MAPPED_TYPE_SET = new Set(['Omit', 'Pick', 'Required', 'Partial']);
+const allowsVirtualTemplate = (type: ts.Type): boolean => DocUtil.readDocTag(type, 'virtual')?.[0]?.trim() === 'true';
 const isMappedType = (type: string | undefined): type is MappedType['operation'] => MAPPED_TYPE_SET.has(type!);
 const getMappedFields = (type: ts.Type): string[] | undefined => {
   if (type.isStringLiteral()) {
@@ -52,9 +53,7 @@ const GLOBAL_SIMPLE: Record<string, Function> = {
   PromiseConstructor: Promise.constructor
 };
 
-type Category =
-  'tuple' | 'shape' | 'literal' | 'template' | 'managed' |
-  'composition' | 'foreign' | 'concrete' | 'unknown' | 'mapped';
+type Category = Exclude<AnyType['key'], 'pointer'> | 'concrete';
 
 /**
  * Type categorizer, input for builder
@@ -137,7 +136,7 @@ export function TypeCategorize(resolver: TransformResolver, type: ts.Type): { ca
  */
 export const TypeBuilder: {
   [K in Category]: {
-    build(resolver: TransformResolver, type: ts.Type, context: { alias?: ts.Symbol, node?: ts.Node }): AnyType | undefined;
+    build(resolver: TransformResolver, type: ts.Type, context: ResolverContext): AnyType | undefined;
     finalize?(type: Type<K>): AnyType;
   }
 } = {
@@ -223,12 +222,31 @@ export const TypeBuilder: {
     }
   },
   managed: {
-    build: (resolver, type) => {
+    build: (resolver, type, context) => {
       const name = CoreUtil.getSymbol(type)?.getName();
       const importName = resolver.getTypeImportName(type)!;
       const tsTypeArguments = resolver.getAllTypeArguments(type);
-      return { key: 'managed', name, importName, tsTypeArguments };
-    }
+      const docs = DocUtil.readDocTag(type, 'see');
+      const innerTypeProperty = docs.find(doc => doc.includes('#target'))?.split(' ')?.[0];
+
+      const managedType: ManagedType = { key: 'managed', name, importName, tsTypeArguments, innerTypeProperty };
+
+      // Detect managed, but shapeable
+      if (tsTypeArguments.length > 0) {
+        const hasEmptyConstructor = type.getConstructSignatures().some(signature => signature.parameters.length === 0)
+          || type.getConstructSignatures().length === 0; // If no constructor, we can assume it's shapeable
+        const hasMethods = type.getProperties().some(property => property.getFlags() & ts.SymbolFlags.Method);
+        if (hasEmptyConstructor && !hasMethods && allowsVirtualTemplate(type)) {
+          return TypeBuilder.shape.build(resolver, type, {
+            ...context,
+            extendsFrom: managedType,
+            alias: type.aliasSymbol
+          });
+        }
+      }
+
+      return managedType;
+    },
   },
   composition: {
     build: (resolver, uType: ts.UnionOrIntersectionType) => {
@@ -311,31 +329,54 @@ export const TypeBuilder: {
   },
   shape: {
     build: (resolver, type, context) => {
-      const tsFieldTypes: Record<string, ts.Type> = {};
-      const name = CoreUtil.getSymbol(context?.alias ?? type)?.getName();
       const importName = resolver.getTypeImportName(type) ?? '<unknown>';
-      const tsTypeArguments = resolver.getAllTypeArguments(type);
       const properties = resolver.getPropertiesOfType(type);
       if (properties.length === 0) {
         return { key: 'literal', name: 'Object', ctor: Object, importName };
       }
 
+      const tsTypeArguments = resolver.getAllTypeArguments(type);
+      const name = CoreUtil.getSymbol(context?.alias ?? type)?.getName();
+      const tsFieldTypes: Record<string, ts.Type> = {};
+
       for (const member of properties) {
-        const decorator = DeclarationUtil.getPrimaryDeclarationNode(member);
-        if (DeclarationUtil.isPublic(decorator)) { // If public
-          const memberType = resolver.getType(decorator);
+        const declaration = DeclarationUtil.getPrimaryDeclarationNode(member);
+        if (DeclarationUtil.isPublic(declaration)) { // IF public
+          const memberType = resolver.getType(declaration);
           if (
             !member.getName().includes('@') && // if not a symbol
             !memberType.getCallSignatures().length // if not a function
           ) {
-            if ((ts.isPropertySignature(decorator) || ts.isPropertyDeclaration(decorator)) && !!decorator.questionToken) {
+            if ((ts.isPropertySignature(declaration) || ts.isPropertyDeclaration(declaration)) && !!declaration.questionToken) {
               Object.defineProperty(memberType, UNDEFINED, { value: true });
             }
             tsFieldTypes[member.getName()] = memberType;
           }
         }
       }
-      return { key: 'shape', name, importName, tsFieldTypes, tsTypeArguments, fieldTypes: {} };
+      return {
+        key: 'shape', name, importName, tsFieldTypes, tsTypeArguments,
+        fieldTypes: {}, extendsFrom: context.extendsFrom, canTemplate: allowsVirtualTemplate(type)
+      };
+    },
+    finalize: (type: ShapeType) => {
+      if ((type.typeArguments?.length ?? 0) > 0 && type.canTemplate !== false) {
+        let suffix = '';
+        const typeTemplateMap = Object.fromEntries(type.typeArguments!.map(node => [node.templateTypeName, node]));
+
+        for (const field of Object.values(type.fieldTypes)) {
+          if (field.key === 'literal' || field.key === 'shape' || field.key === 'managed') {
+            if (field.typeArguments?.every(item => item.templateTypeName && item.templateTypeName in typeTemplateMap)) {
+              field.typeArguments = field.typeArguments.map(item => typeTemplateMap[item.templateTypeName!]);
+              suffix = `${suffix}${field.name}${field.typeArguments.map(arg => arg.name).join('$')}`;
+            }
+          }
+        }
+        if (suffix) {
+          type.name = `${type.name}$${suffix}`;
+        }
+      }
+      return type;
     }
   },
   concrete: {

package/src/resolver/service.ts

@@ -1,14 +1,16 @@
-import type ts from 'typescript';
+import ts from 'typescript';
 
 import { path, type ManifestIndex, ManifestModuleUtil, type IndexedFile } from '@travetto/manifest';
 
-import type { AnyType, TransformResolver } from './types.ts';
+import type { AnyType, ResolverContext, TransformResolver } from './types.ts';
 import { TypeCategorize, TypeBuilder } from './builder.ts';
 import { VisitCache } from './cache.ts';
 import { DocUtil } from '../util/doc.ts';
 import { DeclarationUtil } from '../util/declaration.ts';
 import { transformCast } from '../types/shared.ts';
 
+const isFinalizeType = (key: string): key is keyof typeof TypeBuilder => key in TypeBuilder;
+
 /**
  * Implementation of TransformResolver
  */
@@ -82,8 +84,16 @@ export class SimpleResolver implements TransformResolver {
   /**
    * Fetch all type arguments for a give type
    */
-  getAllTypeArguments(ref: ts.Type): ts.Type[] {
-    return transformCast(this.#tsChecker.getTypeArguments(transformCast(ref)));
+  getAllTypeArguments(ref: ts.Type): [templateName: string, type: ts.Type][] {
+    const types = this.#tsChecker.getTypeArguments(transformCast(ref));
+    let names: string[] | undefined;
+    if (ref.symbol.declarations?.[0]) {
+      const first = ref.symbol.declarations[0];
+      if (ts.isClassLike(first) || ts.isInterfaceDeclaration(first) || ts.isTypeAliasDeclaration(first)) {
+        names = first.typeParameters?.map(tp => tp.name.getText()) ?? [];
+      }
+    }
+    return transformCast(types.map((type, i) => [names?.[i] ?? '$', type]));
   }
 
   /**
@@ -113,18 +123,21 @@ export class SimpleResolver implements TransformResolver {
   /**
    * Resolve an `AnyType` from a `ts.Type` or a `ts.Node`
    */
-  resolveType(node: ts.Type | ts.Node, importName: string): AnyType {
+  resolveType(node: ts.Type | ts.Node | ts.TypeReference, importName: string): AnyType {
     const visited = new VisitCache();
-    const resolve = (resType: ts.Type, alias?: ts.Symbol, depth = 0): AnyType => {
+    const resolve = (resType: ts.Type, context?: Omit<ResolverContext, 'node' | 'importName'>): AnyType => {
+      const { depth = 0 } = context ?? {};
 
       if (depth > 20) { // Max depth is 20
         throw new Error(`Object structure too nested: ${'getText' in node ? node.getText() : ''}`);
       }
 
       const { category, type } = TypeCategorize(this, resType);
-      const { build, finalize } = TypeBuilder[category];
+      // TODO: Figure out how to get this legitimately
+      const typeArguments: ts.Type[] =
+        'resolvedTypeArguments' in resType && resType.resolvedTypeArguments ? transformCast(resType.resolvedTypeArguments) : [];
 
-      let result = build(this, type, { alias, node: node && 'kind' in node ? node : undefined });
+      let result = TypeBuilder[category].build(this, type, { ...context, node: (node && 'kind' in node) ? node : undefined, importName });
 
       // Convert via cache if needed
       result = visited.getOrSet(type, result);
@@ -132,28 +145,35 @@ export class SimpleResolver implements TransformResolver {
       // Recurse
       if (result) {
         result.original = resType;
+        result.templateTypeName = context?.templateTypeName;
+
         try {
-          result.comment = DocUtil.describeDocs(type).description;
+          result.description = DocUtil.describeDocs(type).description;
         } catch { }
 
         if ('tsTypeArguments' in result) {
-          result.typeArguments = result.tsTypeArguments!.map((elType) => resolve(elType, type.aliasSymbol, depth + 1));
+          const tsTypeArguments = result.tsTypeArguments!;
+          if (typeArguments.length) {
+            result.typeArguments = typeArguments.map((item, i) => resolve(item, { alias: type.aliasSymbol, templateTypeName: tsTypeArguments[i][0], depth: depth + 1 }));
+          } else {
+            result.typeArguments = tsTypeArguments.map((item) => resolve(item[1], { alias: type.aliasSymbol, templateTypeName: item[0], depth: depth + 1 }));
+          }
           delete result.tsTypeArguments;
         }
         if ('tsFieldTypes' in result) {
           const fields: Record<string, AnyType> = {};
           for (const [name, fieldType] of Object.entries(result.tsFieldTypes ?? [])) {
-            fields[name] = resolve(fieldType, undefined, depth + 1);
+            fields[name] = resolve(fieldType, { depth: depth + 1 });
           }
           result.fieldTypes = fields;
           delete result.tsFieldTypes;
         }
         if ('tsSubTypes' in result) {
-          result.subTypes = result.tsSubTypes!.map((elType) => resolve(elType, type.aliasSymbol, depth + 1));
+          result.subTypes = result.tsSubTypes!.map((item) => resolve(item, { alias: type.aliasSymbol, depth: depth + 1 }));
           delete result.tsSubTypes;
         }
-        if (finalize) {
-          result = finalize(transformCast(result));
+        if (isFinalizeType(result.key)) {
+          result = TypeBuilder[result.key].finalize?.(transformCast(result)) ?? result;
         }
       }
 

package/src/resolver/types.ts

@@ -1,6 +1,8 @@
 import type ts from 'typescript';
 import type { TemplateLiteral } from '../types/shared.ts';
 
+type TemplateArgument = [templateName: string, type: ts.Type];
+
 /**
  * Base type for a simplistic type structure
  */
@@ -16,7 +18,11 @@ export interface Type<K extends string> {
   /**
    * JS Doc comment
    */
-  comment?: string;
+  description?: string;
+  /**
+   * JS Doc examples
+   */
+  examples?: string[];
   /**
    * Can be undefined
    */
@@ -29,6 +35,10 @@ export interface Type<K extends string> {
    * Original type
    */
   original?: ts.Type;
+  /**
+   * Template name if this type is derived from a template
+   */
+  templateTypeName?: string;
 }
 
 /**
@@ -46,7 +56,11 @@ export interface ManagedType extends Type<'managed'> {
   /**
    * Type Info
    */
-  tsTypeArguments?: ts.Type[];
+  tsTypeArguments?: TemplateArgument[];
+  /**
+   * Inner return property
+   */
+  innerTypeProperty?: string;
 }
 
 /**
@@ -72,7 +86,15 @@ export interface ShapeType extends Type<'shape'> {
   /**
    * Type Arguments
    */
-  tsTypeArguments?: ts.Type[];
+  tsTypeArguments?: TemplateArgument[];
+  /**
+   * Can we template this type
+   */
+  canTemplate?: boolean;
+  /**
+   * Extends from another type, used for shapes that are concrete types, but we want to preserve the shape information as well
+   */
+  extendsFrom?: ManagedType;
 }
 
 /**
@@ -116,7 +138,7 @@ export interface LiteralType extends Type<'literal'> {
   /**
    * Type Info
    */
-  tsTypeArguments?: ts.Type[];
+  tsTypeArguments?: TemplateArgument[];
 }
 
 /**
@@ -213,8 +235,17 @@ export interface TransformResolver {
   isKnownFile(file: string): boolean;
   getFileImportName(file: string, removeExt?: boolean): string;
   getTypeImportName(type: ts.Type, removeExt?: boolean): string | undefined;
-  getAllTypeArguments(type: ts.Type): ts.Type[];
+  getAllTypeArguments(type: ts.Type): TemplateArgument[];
   getPropertiesOfType(type: ts.Type): ts.Symbol[];
   getTypeAsString(type: ts.Type): string | undefined;
   getType(node: ts.Node): ts.Type;
-}
+}
+
+export type ResolverContext = {
+  alias?: ts.Symbol;
+  node?: ts.Node;
+  importName: string;
+  depth?: number;
+  templateTypeName?: string;
+  extendsFrom?: ManagedType;
+};

package/src/types/shared.ts

@@ -14,6 +14,7 @@ export interface ParamDocumentation {
 export interface DeclDocumentation {
   return?: string;
   description?: string;
+  examples?: string[];
   params?: ParamDocumentation[];
 }
 

package/src/util/doc.ts

@@ -32,15 +32,17 @@ export class DocUtil {
     const out: DeclDocumentation = {
       description: undefined,
       return: undefined,
+      examples: undefined,
       params: []
     };
 
     if (toDescribe) {
-      const tags = ts.getJSDocTags(toDescribe);
       while (!this.hasJSDoc(toDescribe) && CoreUtil.hasOriginal(toDescribe)) {
         toDescribe = transformCast<ts.Declaration>(toDescribe.original);
       }
 
+      const tags = ts.getJSDocTags(toDescribe);
+
       const docs = this.hasJSDoc(toDescribe) ? toDescribe.jsDoc : undefined;
 
       if (docs) {
@@ -59,6 +61,8 @@ export class DocUtil {
               name: tag.name && tag.name.getText(),
               description: this.getDocComment(tag, '')!
             });
+          } else if (tag.tagName.getText() === 'example') {
+            (out.examples ??= []).push(this.getDocComment(tag, '')!);
           }
         }
       }