typescript-plugin-mark-fields 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 linsk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# typescript-plugin-mark-fields
+
+[![npm version](https://img.shields.io/npm/v/typescript-plugin-mark-fields.svg)](https://www.npmjs.com/package/typescript-plugin-mark-fields)
+[![License](https://img.shields.io/npm/l/typescript-plugin-mark-fields.svg)](https://github.com/linsk1998/typescript-plugin-mark-fields/blob/main/LICENSE)
+
+TypeScript transformer 插件。编译期自动在每个 class 头部插入 `static {}` 块，将实例字段显式标记到 `prototype` 上，使运行时代码能在实例化之前感知类有哪些字段。
+
+## 快速预览
+
+**输入：**
+
+```ts
+const TAG = 'tag';
+
+class Animal {
+  static count = 0;
+  name;
+  type = 'dog';
+  [TAG];
+  legs = 4;
+}
+```
+
+**输出：**
+
+```js
+const TAG = 'tag';
+
+class Animal {
+  static {
+    this.prototype.name = undefined;
+    this.prototype.type = undefined;
+    this.prototype[TAG] = undefined;
+    this.prototype.legs = undefined;
+  }
+  static count = 0;
+  name;
+  type = 'dog';
+  [TAG];
+  legs = 4;
+}
+```
+
+> `static {}` 中的 `this` 指向类自身，无论具名类还是匿名类表达式均有效。
+
+## 处理规则
+
+| 字段类型 | 示例 | 处理 |
+|---------|------|:---:|
+| 普通标识符字段 | `name` | ✅ `this.prototype.name = undefined` |
+| 带初始值的字段 | `type = "dog"` | ✅ `this.prototype.type = undefined` |
+| 计算属性名 | `[TAG]` | ✅ `this.prototype[TAG] = undefined` |
+| 字符串字面量 key | `"my-field"` | ✅ `this.prototype["my-field"] = undefined` |
+| 数字字面量 key | `0` | ✅ `this.prototype[0] = undefined` |
+| 类表达式 | `const X = class { ... }` | ✅ 同 class 声明一样生效 |
+| static 字段 | `static count = 0` | ❌ 跳过 |
+| 方法 / getter / setter | `greet() {}` | ❌ 跳过 |
+| 无实例字段的类 | 纯方法 | ❌ 不插入 static block |
+
+## 适用场景
+
+- **装饰器方案补充**：未写装饰器的字段也会被标记到 prototype
+- **运行时反射 / ORM / 序列化**：框架在实例化前就能收集字段元数据
+- **AOP 切面注入**：在字段读取/写入时插入拦截逻辑
+- **与 `useDefineForClassFields` 一致的可见语义**：让运行时代码明确知道字段的存在
+
+## 要求
+
+- TypeScript >= 4.4（需要 `static {}` 语法支持）
+
+## 安装
+
+```bash
+npm install typescript-plugin-mark-fields
+```
+
+## 用法
+
+### TypeScript Compiler API
+
+```ts
+import ts from 'typescript';
+import plugin from 'typescript-plugin-mark-fields';
+
+const program = ts.createProgram(['src/index.ts'], {
+  target: ts.ScriptTarget.ESNext,
+});
+
+const transformers: ts.CustomTransformers = {
+  before: [plugin(program, {})],
+};
+
+program.emit(undefined, undefined, undefined, undefined, transformers);
+```
+
+### Rollup
+
+```js
+// rollup.config.js
+import typescript from '@rollup/plugin-typescript';
+import plugin from 'typescript-plugin-mark-fields';
+
+export default {
+  input: 'src/index.ts',
+  plugins: [
+    typescript({
+      transformers: (program) => ({
+        before: [plugin(program, {})],
+      }),
+    }),
+  ],
+};
+```
+
+### Webpack (ts-loader)
+
+```js
+// webpack.config.js
+const plugin = require('typescript-plugin-mark-fields');
+
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.tsx?$/,
+        loader: 'ts-loader',
+        options: {
+          getCustomTransformers: (program) => ({
+            before: [plugin(program, {})],
+          }),
+        },
+      },
+    ],
+  },
+};
+```
+
+### ttypescript / ts-patch
+
+在 `tsconfig.json` 中添加：
+
+```json
+{
+  "compilerOptions": {
+    "plugins": [
+      { "transform": "typescript-plugin-mark-fields" }
+    ]
+  }
+}
+```
+
+然后用 `ttsc` 代替 `tsc` 编译。
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import ts = require('typescript');
+declare function transformerFactory(program: ts.Program, options?: {}): ts.TransformerFactory<ts.SourceFile>;
+declare namespace transformerFactory {
+    var _a: typeof transformerFactory;
+    export { _a as default };
+}
+export = transformerFactory;

package/dist/index.js

@@ -0,0 +1,76 @@
+"use strict";
+const ts = require("typescript");
+/** 检查成员是否有 static 修饰符 */
+function isStatic(member) {
+    if (!member.modifiers)
+        return false;
+    return member.modifiers.some((m) => m.kind === ts.SyntaxKind.StaticKeyword);
+}
+/** 收集非 static 的 class property，返回 key 和 computed 标记 */
+function collectFields(members) {
+    const fields = [];
+    for (const member of members) {
+        if (!ts.isPropertyDeclaration(member))
+            continue;
+        if (isStatic(member))
+            continue;
+        if (ts.isComputedPropertyName(member.name)) {
+            fields.push({ name: member.name.expression, computed: true });
+        }
+        else if (ts.isIdentifier(member.name)) {
+            fields.push({ name: member.name, computed: false });
+        }
+        else if (ts.isStringLiteral(member.name)) {
+            fields.push({ name: member.name, computed: true });
+        }
+        else if (ts.isNumericLiteral(member.name)) {
+            fields.push({ name: member.name, computed: true });
+        }
+    }
+    return fields;
+}
+/** 根据收集的字段信息生成 static {} 块 */
+function createStaticBlock(fields) {
+    const statements = fields.map((f) => {
+        // this.prototype
+        const prototypeAccess = ts.factory.createPropertyAccessExpression(ts.factory.createThis(), ts.factory.createIdentifier('prototype'));
+        // this.prototype[key] 或 this.prototype.key
+        const memberAccess = f.computed
+            ? ts.factory.createElementAccessExpression(prototypeAccess, f.name)
+            : ts.factory.createPropertyAccessExpression(prototypeAccess, f.name);
+        // this.prototype[key] = undefined
+        const assignment = ts.factory.createAssignment(memberAccess, ts.factory.createIdentifier('undefined'));
+        return ts.factory.createExpressionStatement(assignment);
+    });
+    return ts.factory.createClassStaticBlockDeclaration(ts.factory.createBlock(statements, true));
+}
+function transformerFactory(program, options = {}) {
+    return (context) => {
+        function visit(node) {
+            if (ts.isClassDeclaration(node) || ts.isClassExpression(node)) {
+                return transformClass(node);
+            }
+            return ts.visitEachChild(node, visit, context);
+        }
+        function transformClass(node) {
+            const fields = collectFields(node.members);
+            if (fields.length === 0) {
+                return node;
+            }
+            const staticBlock = createStaticBlock(fields);
+            // 把 static {} 插到 class body 最前面
+            const newMembers = ts.factory.createNodeArray([staticBlock, ...node.members]);
+            if (ts.isClassDeclaration(node)) {
+                return ts.factory.updateClassDeclaration(node, node.modifiers, node.name, node.typeParameters, node.heritageClauses, newMembers);
+            }
+            else {
+                return ts.factory.updateClassExpression(node, node.modifiers, node.name, node.typeParameters, node.heritageClauses, newMembers);
+            }
+        }
+        return (sourceFile) => {
+            return ts.visitNode(sourceFile, visit);
+        };
+    };
+}
+transformerFactory.default = transformerFactory;
+module.exports = transformerFactory;

package/package.json

@@ -0,0 +1,58 @@
+{
+	"name": "typescript-plugin-mark-fields",
+	"version": "1.0.0",
+	"description": "Auto-mark class fields on prototype via static block for runtime introspection",
+	"keywords": [
+		"typescript",
+		"transformer",
+		"plugin",
+		"class",
+		"fields",
+		"prototype",
+		"static-block",
+		"decorator",
+		"reflect-metadata",
+		"runtime",
+		"introspection",
+		"ttypescript"
+	],
+	"author": "linsk",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/linsk1998/typescript-plugin-mark-fields.git"
+	},
+	"bugs": {
+		"url": "https://github.com/linsk1998/typescript-plugin-mark-fields/issues"
+	},
+	"homepage": "https://github.com/linsk1998/typescript-plugin-mark-fields#readme",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "rimraf dist && tsc",
+		"gen-fixtures": "rimraf tests/fixtures && ttsc -p ./tests/tsconfig.json --noEmit false",
+		"test": "mocha tests/**/*.test.js",
+		"prepublishOnly": "npm run build && npm run test"
+	},
+	"peerDependencies": {
+		"typescript": ">=4.4"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	},
+	"devDependencies": {
+		"@rollup/plugin-typescript": "^12.1.4",
+		"mocha": "^8.0.1",
+		"rimraf": "^6.0.1",
+		"rollup": "3.0.0",
+		"ts-loader": "^9.5.4",
+		"tslib": "^2.8.1",
+		"ttypescript": "^1.5.15",
+		"typescript": "^4.9.5",
+		"webpack": "^5.102.1"
+	}
+}