ts-const-value-transformer 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## v0.2.0
+
+Add following options:
+
+- `hoistEnumValues`
+- `hoistExternalValues`
+- `hoistPureFunctionCall`
+
+## v0.1.1
+
+Add `createTransformer` export point
+
 ## v0.1.0
 
 Initial version.

package/README.md

@@ -150,14 +150,20 @@ export interface TransformOptions {
   ts?: typeof ts;
   /** Hoist property expressions (`x.prop`) which the value is constant. Default is true, but if the property getter has side effects (not recommended), set false explicitly. */
   hoistProperty?: boolean | undefined;
+  /** Hoist TypeScript's `enum` values (which are constant). Default is true, but if you want to preserve references, set false explicitly. Note that TypeScript compiler erases `const enum` references unless `preserveConstEnums` is true. */
+  hoistEnumValues?: boolean | undefined;
+  /** Hoist values defined in the external libraries. Default is true, but if the external libraries are not bundled, set false explicitly to keep references. */
+  hoistExternalValues?: boolean | undefined;
   /** Hoist function calls which the return value is constant. Default is false because function calls may have side effects. */
   unsafeHoistFunctionCall?: boolean | undefined;
+  /** Hoist function calls, with `@__PURE__` (or `#__PURE__`) comment annotation (must be a multi-line comment), which the return value is constant. Default is false, but if the function really has no side effects, you can safely specify true. If true, `unsafeHoistFunctionCall` option is ignored for `@__PURE__` functions */
+  hoistPureFunctionCall?: boolean | undefined;
   /** Hoist expressions with `as XXX`. Default is false because the base (non-`as`) value may be non-constant. */
   unsafeHoistAsExpresion?: boolean | undefined;
 }
 ```
 
-Note that you must pass `options` field to `createTransformer` function or `"plugins"` specifier.
+Note that you must pass `options` field to `createTransformer` function or `"plugins"` specifier (see above examples).
 
 ### APIs
 

package/dist/transform.d.mts

@@ -5,8 +5,14 @@ export interface TransformOptions {
     ts?: typeof ts;
     /** Hoist property expressions (`x.prop`) which the value is constant. Default is true, but if the property getter has side effects (not recommended), set false explicitly. */
     hoistProperty?: boolean | undefined;
+    /** Hoist TypeScript's `enum` values (which are constant). Default is true, but if you want to preserve references, set false explicitly. Note that TypeScript compiler erases `const enum` references unless `preserveConstEnums` is true. */
+    hoistEnumValues?: boolean | undefined;
+    /** Hoist values defined in the external libraries. Default is true, but if the external libraries are not bundled, set false explicitly to keep references. */
+    hoistExternalValues?: boolean | undefined;
     /** Hoist function calls which the return value is constant. Default is false because function calls may have side effects. */
     unsafeHoistFunctionCall?: boolean | undefined;
+    /** Hoist function calls, with `@__PURE__` (or `#__PURE__`) comment annotation (must be a multi-line comment), which the return value is constant. Default is false, but if the function really has no side effects, you can safely specify true. If true, `unsafeHoistFunctionCall` option is ignored for `@__PURE__` functions */
+    hoistPureFunctionCall?: boolean | undefined;
     /** Hoist expressions with `as XXX`. Default is false because the base (non-`as`) value may be non-constant. */
     unsafeHoistAsExpresion?: boolean | undefined;
 }

package/dist/transform.mjs

@@ -1,13 +1,16 @@
 import * as sourceMap from 'source-map';
 import * as ts from 'typescript';
 const SYMBOL_ORIGINAL_NODE = Symbol('originalNode');
-function assignDefaultValues(options) {
+function assignDefaultValues(options = {}) {
     return {
-        ts,
-        hoistProperty: true,
-        unsafeHoistAsExpresion: false,
-        unsafeHoistFunctionCall: false,
-        ...options,
+        // avoid using spread syntax to override `undefined` (not missing) values
+        ts: options.ts ?? ts,
+        hoistProperty: options.hoistProperty ?? true,
+        hoistEnumValues: options.hoistEnumValues ?? true,
+        hoistExternalValues: options.hoistExternalValues ?? true,
+        unsafeHoistAsExpresion: options.unsafeHoistAsExpresion ?? false,
+        hoistPureFunctionCall: options.hoistPureFunctionCall ?? false,
+        unsafeHoistFunctionCall: options.unsafeHoistFunctionCall ?? false,
     };
 }
 ////////////////////////////////////////////////////////////////////////////////
@@ -37,12 +40,24 @@ function visitNodeAndReplaceIfNeeded(node, sourceFile, program, context, options
         (!options.hoistProperty &&
             ts.isPropertyAccessExpression(node) &&
             !isEnumAccess(node, program, ts)) ||
-        (!options.unsafeHoistFunctionCall && ts.isCallLikeExpression(node)) ||
+        (!options.hoistEnumValues &&
+            ((ts.isPropertyAccessExpression(node) &&
+                isEnumAccess(node, program, ts)) ||
+                (ts.isIdentifier(node) && isEnumIdentifier(node, program, ts)))) ||
         node.kind === ts.SyntaxKind.TrueKeyword ||
         node.kind === ts.SyntaxKind.FalseKeyword ||
         node.kind === ts.SyntaxKind.NullKeyword) {
         return node;
     }
+    if (!options.unsafeHoistFunctionCall &&
+        (!options.hoistPureFunctionCall || !hasPureAnnotation(node, sourceFile, ts))) {
+        if (ts.isCallLikeExpression(node)) {
+            return node;
+        }
+    }
+    if (!options.hoistExternalValues && isExternalReference(node, program)) {
+        return node;
+    }
     if (ts.isIdentifier(node)) {
         if (
         // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
@@ -111,6 +126,43 @@ function isEnumAccess(node, program, tsInstance) {
     const type = typeChecker.getTypeAtLocation(node);
     return (type.getFlags() & ts.TypeFlags.EnumLiteral) !== 0;
 }
+function isEnumIdentifier(node, program, tsInstance) {
+    const ts = tsInstance;
+    const typeChecker = program.getTypeChecker();
+    const type = typeChecker.getTypeAtLocation(node);
+    return (type.getFlags() & ts.TypeFlags.EnumLiteral) !== 0;
+}
+function isExternalReference(node, program) {
+    const typeChecker = program.getTypeChecker();
+    const nodeSym = typeChecker.getSymbolAtLocation(node);
+    let nodeFrom = nodeSym?.getDeclarations()?.[0];
+    while (nodeFrom) {
+        if (program.isSourceFileFromExternalLibrary(nodeFrom.getSourceFile())) {
+            return true;
+        }
+        // Walk into the 'import' variables
+        if (!ts.isImportSpecifier(nodeFrom)) {
+            break;
+        }
+        const baseName = nodeFrom.propertyName ?? nodeFrom.name;
+        const baseSym = typeChecker.getSymbolAtLocation(baseName);
+        nodeFrom = baseSym?.getDeclarations()?.[0];
+    }
+    const type = typeChecker.getTypeAtLocation(node);
+    const sym = type.getSymbol();
+    if (!sym) {
+        return false;
+    }
+    const def = sym.getDeclarations()?.[0];
+    if (!def) {
+        return false;
+    }
+    const typeDefinitionSource = def.getSourceFile();
+    if (program.isSourceFileFromExternalLibrary(typeDefinitionSource)) {
+        return true;
+    }
+    return false;
+}
 function isAsConstExpression(node) {
     return node.type.getText() === 'const';
 }
@@ -145,6 +197,21 @@ function hasParentAsExpression(node, context, tsInstance) {
     }
     return hasParentAsExpression(node.parent, context, ts);
 }
+function hasPureAnnotation(node, sourceFile, tsInstance) {
+    const ts = tsInstance;
+    const fullText = node.getFullText(sourceFile);
+    const ranges = ts.getLeadingCommentRanges(fullText, 0) ?? [];
+    for (const range of ranges) {
+        if (range.kind !== ts.SyntaxKind.MultiLineCommentTrivia) {
+            continue;
+        }
+        const text = fullText.slice(range.pos + 2, range.end - 2).trim();
+        if ((text[0] === '@' || text[0] === '#') && text.slice(1) === '__PURE__') {
+            return true;
+        }
+    }
+    return false;
+}
 ////////////////////////////////////////////////////////////////////////////////
 export function printSource(sourceFile) {
     return printSourceImpl(sourceFile)[0];

package/dist/version.d.mts

@@ -1,2 +1,2 @@
-declare const _default: "0.1.0";
+declare const _default: "0.2.0";
 export default _default;

package/dist/version.mjs

@@ -1 +1 @@
-export default '0.1.0';
+export default '0.2.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-const-value-transformer",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "engines": {
     "node": ">=20.19.3"
   },
@@ -13,6 +13,16 @@
       "import": "./dist/index.mjs",
       "types": "./dist/index.d.mts"
     },
+    "./createTransformer": {
+      "default": "./dist/createTransformer.mjs",
+      "import": "./dist/createTransformer.mjs",
+      "types": "./dist/createTransformer.d.mts"
+    },
+    "./createTransformer.mjs": {
+      "default": "./dist/createTransformer.mjs",
+      "import": "./dist/createTransformer.mjs",
+      "types": "./dist/createTransformer.d.mts"
+    },
     "./getCustomTransformers": {
       "default": "./dist/getCustomTransformers.mjs",
       "import": "./dist/getCustomTransformers.mjs",