@travetto/transformer 8.0.0-alpha.9 → 8.0.0

package/README.md

@@ -15,15 +15,15 @@ yarn add @travetto/transformer
 
 This module provides support for enhanced AST transformations, and declarative transformer registration, with common patterns to support all the transformers used throughout the framework. Transformations are located by `support/transformer.<name>.ts` as the filename. 
 
-The module is primarily aimed at extremely advanced usages for things that cannot be detected at runtime.  The [Registry](https://github.com/travetto/travetto/tree/main/module/registry#readme "Patterns and utilities for handling registration of metadata and functionality for run-time use") module already has knowledge of all `class`es and `field`s, and is able to listen to changes there.  Many of the modules build upon work by some of the foundational transformers defined in [Manifest](https://github.com/travetto/travetto/tree/main/module/manifest#readme "Support for project indexing, manifesting, along with file watching"), [Registry](https://github.com/travetto/travetto/tree/main/module/registry#readme "Patterns and utilities for handling registration of metadata and functionality for run-time use"), [Schema](https://github.com/travetto/travetto/tree/main/module/schema#readme "Data type registry for runtime validation, reflection and binding.") and [Dependency Injection](https://github.com/travetto/travetto/tree/main/module/di#readme "Dependency registration/management and injection support.").  These all center around defining a registry of classes, and associated type information. 
+The module is primarily aimed at extremely advanced usages for things that cannot be detected at runtime. The [Registry](https://github.com/travetto/travetto/tree/main/module/registry#readme "Patterns and utilities for handling registration of metadata and functionality for run-time use") module already has knowledge of all `class`es and `field`s, and is able to listen to changes there. Many of the modules build upon work by some of the foundational transformers defined in [Manifest](https://github.com/travetto/travetto/tree/main/module/manifest#readme "Support for project indexing, manifesting, along with file watching"), [Registry](https://github.com/travetto/travetto/tree/main/module/registry#readme "Patterns and utilities for handling registration of metadata and functionality for run-time use"), [Schema](https://github.com/travetto/travetto/tree/main/module/schema#readme "Data type registry for runtime validation, reflection and binding.") and [Dependency Injection](https://github.com/travetto/travetto/tree/main/module/di#readme "Dependency registration/management and injection support."). These all center around defining a registry of classes, and associated type information. 
 
 Because working with the [Typescript](https://typescriptlang.org) API can be delicate (and open to breaking changes), creating new transformers should be done cautiously.
 
 ## Monorepos and Idempotency
-Within the framework, any build or compile step will target the entire workspace, and for mono-repo projects, will include all modules.  The optimization this provides is great, but comes with a strict requirement that all compilation processes need to be idempotent.  This means that compiling a module directly, versus as a dependency should always produce the same output. This produces a requirement that all transformers are opt-in by the source code, and which transformers are needed in a file should be code-evident.  This also means that no transformers are optional, as that could produce different output depending on the dependency graph for a given module.
+Within the framework, any build or compile step will target the entire workspace, and for mono-repo projects, will include all modules. The optimization this provides is great, but comes with a strict requirement that all compilation processes need to be idempotent. This means that compiling a module directly, versus as a dependency should always produce the same output. This produces a requirement that all transformers are opt-in by the source code, and which transformers are needed in a file should be code-evident. This also means that no transformers are optional, as that could produce different output depending on the dependency graph for a given module.
 
 ## Custom Transformer
-Below is an example of a transformer that upper cases all `class`, `method` and `param` declarations.  This will break any code that depends upon it as we are redefining all the identifiers at compile time.
+Below is an example of a transformer that upper cases all `class`, `method` and `param` declarations. This will break any code that depends upon it as we are redefining all the identifiers at compile time.
 
 **Code: Sample Transformer - Upper case all declarations**
 ```typescript
@@ -32,7 +32,6 @@ import type ts from 'typescript';
 import { TransformerHandler, type TransformerState } from '@travetto/transformer';
 
 export class MakeUpper {
-
   static isValid(state: TransformerState): boolean {
     return state.importName !== '@travetto/transformer/doc/upper.ts';
   }
@@ -44,39 +43,45 @@ export class MakeUpper {
   }
 
   static handleProperty(state: TransformerState, node: ts.PropertyDeclaration): ts.PropertyDeclaration {
-    return !this.isValid(state) ? node : state.factory.updatePropertyDeclaration(
-      node,
-      node.modifiers,
-      node.name.getText().toUpperCase(),
-      undefined,
-      node.type,
-      node.initializer ?? state.createIdentifier('undefined')
-    );
+    return !this.isValid(state)
+      ? node
+      : state.factory.updatePropertyDeclaration(
+          node,
+          node.modifiers,
+          node.name.getText().toUpperCase(),
+          undefined,
+          node.type,
+          node.initializer ?? state.createIdentifier('undefined')
+        );
   }
 
   static handleClass(state: TransformerState, node: ts.ClassDeclaration): ts.ClassDeclaration {
-    return !this.isValid(state) ? node : state.factory.updateClassDeclaration(
-      node,
-      node.modifiers,
-      state.createIdentifier(node.name!.getText().toUpperCase()),
-      node.typeParameters,
-      node.heritageClauses,
-      node.members
-    );
+    return !this.isValid(state)
+      ? node
+      : state.factory.updateClassDeclaration(
+          node,
+          node.modifiers,
+          state.createIdentifier(node.name!.getText().toUpperCase()),
+          node.typeParameters,
+          node.heritageClauses,
+          node.members
+        );
   }
 
   static handleMethod(state: TransformerState, node: ts.MethodDeclaration): ts.MethodDeclaration {
-    return !this.isValid(state) ? node : state.factory.updateMethodDeclaration(
-      node,
-      node.modifiers,
-      undefined,
-      state.createIdentifier(node.name.getText().toUpperCase()),
-      undefined,
-      node.typeParameters,
-      node.parameters,
-      node.type,
-      node.body
-    );
+    return !this.isValid(state)
+      ? node
+      : state.factory.updateMethodDeclaration(
+          node,
+          node.modifiers,
+          undefined,
+          state.createIdentifier(node.name.getText().toUpperCase()),
+          undefined,
+          node.typeParameters,
+          node.parameters,
+          node.type,
+          node.body
+        );
   }
 }
 ```
@@ -91,7 +96,7 @@ export class Test {
   dob: Date;
 
   computeAge(): void {
-    this['age'] = (Date.now() - this.dob.getTime());
+    this.age = Date.now() - this.dob.getTime();
   }
 }
 ```
@@ -101,12 +106,12 @@ export class Test {
 import * as Δfunction from "@travetto/runtime/src/function.js";
 const Δm_1 = ["@travetto/transformer", "doc/upper.ts"];
 export class TEST {
-    static { Δfunction.registerFunction(TEST, Δm_1, { hash: 649563175, lines: [1, 9] }, { COMPUTEAGE: { hash: 1286718349, lines: [6, 8, 7] } }, false); }
+    static { Δfunction.registerFunction(TEST, Δm_1, { hash: 2002713074, lines: [1, 9] }, { COMPUTEAGE: { hash: 731903366, lines: [6, 8, 7] } }, false); }
     NAME;
     AGE;
     DOB;
     COMPUTEAGE() {
-        this['AGE'] = (Date.now() - this.DOB.getTime());
+        this.AGE = Date.now() - this.DOB.getTime();
     }
 }
 ```

package/__index__.ts

@@ -1,10 +1,20 @@
-export * from './src/state.ts';
-export * from './src/visitor.ts';
+export * from './src/manager.ts';
 export * from './src/register.ts';
-export * from './src/types/visitor.ts';
+export type {
+  AnyType,
+  CompositionType,
+  ForeignType,
+  LiteralType,
+  ManagedType,
+  PointerType,
+  ShapeType,
+  TemplateType,
+  TupleType,
+  UnknownType
+} from './src/resolver/types.ts';
+export * from './src/state.ts';
 export * from './src/types/shared.ts';
-export * from './src/manager.ts';
-
+export * from './src/types/visitor.ts';
 export * from './src/util/core.ts';
 export * from './src/util/declaration.ts';
 export * from './src/util/decorator.ts';
@@ -12,8 +22,4 @@ export * from './src/util/doc.ts';
 export * from './src/util/literal.ts';
 export * from './src/util/log.ts';
 export * from './src/util/system.ts';
-
-export type {
-  AnyType, ForeignType, ManagedType, PointerType, LiteralType, ShapeType,
-  CompositionType, TupleType, UnknownType, TemplateType
-} from './src/resolver/types.ts';
+export * from './src/visitor.ts';

package/package.json

@@ -1,31 +1,34 @@
 {
   "name": "@travetto/transformer",
-  "version": "8.0.0-alpha.9",
-  "type": "module",
+  "version": "8.0.0",
   "description": "Functionality for AST transformations, with transformer registration, and general utils",
   "keywords": [
-    "typescript",
     "ast-transformations",
-    "travetto"
+    "travetto",
+    "typescript"
   ],
   "homepage": "https://travetto.io",
   "license": "MIT",
   "author": {
-    "email": "travetto.framework@gmail.com",
-    "name": "Travetto Framework"
+    "name": "Travetto Framework",
+    "email": "travetto.framework@gmail.com"
+  },
+  "repository": {
+    "url": "git+https://github.com/travetto/travetto.git",
+    "directory": "module/transformer"
   },
   "files": [
     "__index__.ts",
     "src",
     "support"
   ],
+  "type": "module",
   "main": "__index__.ts",
-  "repository": {
-    "url": "git+https://github.com/travetto/travetto.git",
-    "directory": "module/transformer"
+  "publishConfig": {
+    "access": "public"
   },
   "dependencies": {
-    "@travetto/manifest": "^8.0.0-alpha.7",
+    "@travetto/manifest": "^8.0.0",
     "tslib": "^2.8.1",
     "typescript": "^6.0.2"
   },
@@ -34,8 +37,5 @@
     "roles": [
       "compile"
     ]
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/importer.ts

@@ -2,12 +2,12 @@ import ts from 'typescript';
 
 import { ManifestModuleUtil, PackageUtil, path } from '@travetto/manifest';
 
-import type { AnyType, TransformResolver, ManagedType, MappedType } from './resolver/types.ts';
-import { ImportUtil } from './util/import.ts';
-import { CoreUtil } from './util/core.ts';
+import type { AnyType, ManagedType, MappedType, TransformResolver } from './resolver/types.ts';
 import type { Import } from './types/shared.ts';
-import { LiteralUtil } from './util/literal.ts';
+import { CoreUtil } from './util/core.ts';
 import { DeclarationUtil } from './util/declaration.ts';
+import { ImportUtil } from './util/import.ts';
+import { LiteralUtil } from './util/literal.ts';
 
 const D_OR_D_TS_EXT_REGEX = /[.]d([.]ts)?$/;
 
@@ -15,7 +15,6 @@ const D_OR_D_TS_EXT_REGEX = /[.]d([.]ts)?$/;
  * Manages imports within a ts.SourceFile
  */
 export class ImportManager {
-
   #newImports = new Map<string, Import>();
   #imports: Map<string, Import>;
   #idx: Record<string, number> = {};
@@ -51,19 +50,13 @@ export class ImportManager {
         const type = this.#resolver.getType(element.name);
         const objFlags = DeclarationUtil.getObjectFlags(type);
         const typeFlags = type.getFlags();
-        // eslint-disable-next-line no-bitwise
         if (!(objFlags & (ts.SymbolFlags.Type | ts.SymbolFlags.Interface)) || !(typeFlags & ts.TypeFlags.Any)) {
           newBindings.push(element);
         }
       }
     }
     if (newBindings.length !== bindings.elements.length) {
-      return this.factory.updateImportClause(
-        clause,
-        clause.isTypeOnly,
-        clause.name,
-        this.factory.createNamedImports(newBindings)
-      );
+      return this.factory.updateImportClause(clause, clause.isTypeOnly, clause.name, this.factory.createNamedImports(newBindings));
     } else {
       return clause;
     }
@@ -82,9 +75,7 @@ export class ImportManager {
       }
     }
 
-    return fileOrImport ?
-      (fileOrImport.startsWith('.') || this.#resolver.isKnownFile(fileOrImport)) :
-      false;
+    return fileOrImport ? fileOrImport.startsWith('.') || this.#resolver.isKnownFile(fileOrImport) : false;
   }
 
   /**
@@ -96,10 +87,8 @@ export class ImportManager {
 
       const type = ManifestModuleUtil.getFileType(specText);
       if (type === 'js' || type === 'ts') {
-        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
         return LiteralUtil.fromLiteral(this.factory, ManifestModuleUtil.withOutputExtension(specText)) as unknown as T;
       } else {
-        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
         return LiteralUtil.fromLiteral(this.factory, `${specText}${ManifestModuleUtil.OUTPUT_EXT}`) as unknown as T;
       }
     }
@@ -115,7 +104,7 @@ export class ImportManager {
         return this.factory.createIdentifier(name);
       } else {
         const key = path.basename(file, path.extname(file)).replace(/\W+/g, '_');
-        const suffix = this.#idx[key] = (this.#idx[key] ?? -1) + 1;
+        const suffix = (this.#idx[key] = (this.#idx[key] ?? -1) + 1);
         return this.factory.createIdentifier(`Δ${key}${suffix ? suffix : ''}`);
       }
     });
@@ -140,7 +129,8 @@ export class ImportManager {
       const identifier = this.getIdentifier(file, name);
       const uniqueName = identifier.text;
 
-      if (this.#imports.has(uniqueName)) { // Already imported, be cool
+      if (this.#imports.has(uniqueName)) {
+        // Already imported, be cool
         return this.#imports.get(uniqueName)!;
       }
 
@@ -161,10 +151,16 @@ export class ImportManager {
       }
       switch (type.key) {
         case 'managed':
-        case 'literal': this.importFromResolved(...type.typeArguments || []); break;
+        case 'literal':
+          this.importFromResolved(...(type.typeArguments || []));
+          break;
         case 'composition':
-        case 'tuple': this.importFromResolved(...type.subTypes || []); break;
-        case 'shape': this.importFromResolved(...Object.values(type.fieldTypes)); break;
+        case 'tuple':
+          this.importFromResolved(...(type.subTypes || []));
+          break;
+        case 'shape':
+          this.importFromResolved(...Object.values(type.fieldTypes));
+          break;
       }
     }
   }
@@ -191,7 +187,8 @@ export class ImportManager {
         ...importStmts,
         ...file.statements.filter((node: ts.Statement & { remove?: boolean }) => !node.remove) // Exclude culled imports
       ]);
-    } catch (error) { // Missing import
+    } catch (error) {
+      // Missing import
       if (!(error instanceof Error)) {
         throw error;
       }
@@ -207,24 +204,28 @@ export class ImportManager {
     for (const statement of source.statements) {
       if (ts.isExportDeclaration(statement)) {
         if (!statement.isTypeOnly) {
-          toAdd.push(this.factory.updateExportDeclaration(
-            statement,
-            statement.modifiers,
-            statement.isTypeOnly,
-            statement.exportClause,
-            this.normalizeModuleSpecifier(statement.moduleSpecifier),
-            statement.attributes
-          ));
+          toAdd.push(
+            this.factory.updateExportDeclaration(
+              statement,
+              statement.modifiers,
+              statement.isTypeOnly,
+              statement.exportClause,
+              this.normalizeModuleSpecifier(statement.moduleSpecifier),
+              statement.attributes
+            )
+          );
         }
       } else if (ts.isImportDeclaration(statement)) {
         if (statement.importClause?.phaseModifier !== ts.SyntaxKind.TypeKeyword) {
-          toAdd.push(this.factory.updateImportDeclaration(
-            statement,
-            statement.modifiers,
-            this.#rewriteImportClause(statement.moduleSpecifier, statement.importClause)!,
-            this.normalizeModuleSpecifier(statement.moduleSpecifier)!,
-            statement.attributes
-          ));
+          toAdd.push(
+            this.factory.updateImportDeclaration(
+              statement,
+              statement.modifiers,
+              this.#rewriteImportClause(statement.moduleSpecifier, statement.importClause)!,
+              this.normalizeModuleSpecifier(statement.moduleSpecifier)!,
+              statement.attributes
+            )
+          );
         }
       } else {
         toAdd.push(statement);
@@ -255,4 +256,4 @@ export class ImportManager {
       return factory.createPropertyAccessExpression(identifier, targetName);
     }
   }
-}
+}

package/src/manager.ts

@@ -2,16 +2,15 @@ import type ts from 'typescript';
 
 import type { ManifestIndex } from '@travetto/manifest';
 
+import { getAllTransformers } from './register.ts';
+import { TransformerState } from './state.ts';
 import type { NodeTransformer } from './types/visitor.ts';
 import { VisitorFactory } from './visitor.ts';
-import { TransformerState } from './state.ts';
-import { getAllTransformers } from './register.ts';
 
 /**
  * Manages the typescript transformers
  */
 export class TransformerManager {
-
   /**
    * Create transformer manager
    * @param transformerFiles
@@ -23,16 +22,19 @@ export class TransformerManager {
 
     const transformers: NodeTransformer<TransformerState>[] = [];
 
-    for (const file of transformerFiles) { // Exclude based on blacklist
+    for (const file of transformerFiles) {
+      // Exclude based on blacklist
       const entry = manifestIndex.getEntry(file)!;
       transformers.push(...getAllTransformers(await import(entry.import), entry.module));
     }
 
     for (const transformer of transformers) {
       process.send?.({
-        type: 'log', payload: {
+        type: 'log',
+        payload: {
           level: 'debug',
-          message: `Loaded Transformer: ${transformer.key}#${transformer.type}`, scope: 'transformers'
+          message: `Loaded Transformer: ${transformer.key}#${transformer.type}`,
+          scope: 'transformers'
         }
       });
     }
@@ -72,4 +74,4 @@ export class TransformerManager {
   get(): ts.CustomTransformers | undefined {
     return this.#cached!;
   }
-}
+}

package/src/register.ts

@@ -1,4 +1,4 @@
-import { type NodeTransformer, type TransformPhase, type TransformerType, type Transformer, ModuleNameSymbol } from './types/visitor.ts';
+import { ModuleNameSymbol, type NodeTransformer, type Transformer, type TransformerType, type TransformPhase } from './types/visitor.ts';
 
 const HandlersSymbol = Symbol();
 
@@ -18,7 +18,7 @@ export function getAllTransformers(inputs: Record<string, { [HandlersSymbol]?: N
       if (isTransformer(value)) {
         value[ModuleNameSymbol] = module;
       }
-      return (value[HandlersSymbol] ?? []);
+      return value[HandlersSymbol] ?? [];
     })
     .map(handler => ({
       ...handler,
@@ -28,6 +28,12 @@ export function getAllTransformers(inputs: Record<string, { [HandlersSymbol]?: N
 }
 
 // Store handlers in class
-export function TransformerHandler(cls: TransformerWithHandlers, fn: Function, phase: TransformPhase, type: TransformerType, target?: string[]): void {
+export function TransformerHandler(
+  cls: TransformerWithHandlers,
+  fn: Function,
+  phase: TransformPhase,
+  type: TransformerType,
+  target?: string[]
+): void {
   (cls[HandlersSymbol] ??= []).push({ key: fn.name, [phase]: fn.bind(cls), type, target });
-}
+}