restfuncs-transformer 0.9.8 → 1.0.0

package/index.ts

@@ -1,4 +1,89 @@
-// Just pass-through the default export of typescript-rtti/dist/transformer
-// May be later, we need to extend the transformer for runtime inspection JSDoc information
-import transformer from "typescript-rtti/dist/transformer";
-export default transformer
+import ts, {CompilerHost, CompilerOptions, Program, SourceFile} from 'typescript';
+import {PluginConfig, ProgramTransformerExtras} from "ts-patch";
+import {AddRemoteMethodsMeta} from "./AddRemoteMethodsMeta";
+import {FileTransformRun, TransformerFactoryOOP} from "./transformerUtil";
+
+// From: https://github.com/nonara/ts-patch/discussions/29#discussioncomment-325979
+
+export const transformerVersion = {major: 1,  feature: 1 }
+
+/* ****************************************************************************************************************** */
+// region: Helpers
+/* ****************************************************************************************************************** */
+
+/**
+ * Patches existing Compiler Host (or creates new one) to allow feeding updated file content from cache
+ */
+function getPatchedHost(
+    maybeHost: CompilerHost | undefined,
+    tsInstance: typeof ts,
+    compilerOptions: CompilerOptions
+): CompilerHost & { fileCache: Map<string, SourceFile> }
+{
+    const fileCache = new Map();
+    const compilerHost = maybeHost ?? tsInstance.createCompilerHost(compilerOptions, true);
+    const originalGetSourceFile = compilerHost.getSourceFile;
+
+    return Object.assign(compilerHost, {
+        getSourceFile(fileName: string, languageVersion: ts.ScriptTarget) {
+            fileName = tsInstance.normalizePath(fileName);
+            if (fileCache.has(fileName)) return fileCache.get(fileName);
+
+            const sourceFile = originalGetSourceFile.apply(void 0, Array.from(arguments) as any);
+            fileCache.set(fileName, sourceFile);
+
+            return sourceFile;
+        },
+        fileCache
+    });
+}
+
+// endregion
+
+
+/* ****************************************************************************************************************** */
+// region: Program Transformer
+/* ****************************************************************************************************************** */
+
+export default function transformProgram(
+    program: Program,
+    host: CompilerHost | undefined,
+    config: PluginConfig,
+    extras?: ProgramTransformerExtras,
+): Program {
+    if(!extras) {
+        throw new Error(`Please add the flag "transformProgram": true to the transformer inside tsconfig.json`);
+    }
+
+    const { ts: tsInstance } = extras;
+    const compilerOptions = program.getCompilerOptions();
+    const compilerHost = getPatchedHost(host, tsInstance, compilerOptions);
+    const rootFileNames = program.getRootFileNames().map(tsInstance.normalizePath);
+
+    const transformerFactoryOOP = new TransformerFactoryOOP(AddRemoteMethodsMeta);
+
+    /* Transform AST */
+    tsInstance.transform(
+        /* sourceFiles */ program.getSourceFiles().filter(sourceFile => rootFileNames.includes(sourceFile.fileName)),
+        /* transformerFactoryOOP */ [ transformerFactoryOOP.asFunction ],
+        compilerOptions
+    )
+
+    transformerFactoryOOP.transformRunsDone.forEach(transformRun => {
+        if(transformRun.astWasModified) {
+            /* Render modified files and create new SourceFiles for them to use in host's cache */
+            const {printFile} = tsInstance.createPrinter();
+            const sourceFile = transformRun.sourceFile;
+            const updatedSourceFile = tsInstance.createSourceFile(sourceFile.fileName, printFile(sourceFile), sourceFile.languageVersion);
+            updatedSourceFile.version = `${sourceFile.version}_restfuncs_${transformerVersion.major}.${transformerVersion.feature}`;
+            compilerHost.fileCache.set(sourceFile.fileName, updatedSourceFile);
+        }
+    })
+
+
+
+    /* Re-create Program instance */
+    return tsInstance.createProgram(rootFileNames, compilerOptions, compilerHost);
+}
+
+// endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "restfuncs-transformer",
-  "version": "0.9.8",
+  "version": "1.0.0",
   "description": "Enhances your classes with typescript-rtti, to make them usable with Restfuncs",
   "keywords": ["rpc","rest"],
   "author": "Boris Gingold <bogeee@bogitech.de>",
@@ -11,8 +11,9 @@
   },
   "license": "MIT",
   "scripts": {
-    "clean": "tsc --build --clean && rm -rf dist LICENSE",
-    "build": "tsc"
+    "clean": "tsc --build --clean && rimraf dist LICENSE",
+    "build": "tsc --build",
+    "dev:playgrund": "tsx devPlayground.ts"
   },
   "exports": {
     ".": {
@@ -20,10 +21,13 @@
     }
   },
   "dependencies": {
-    "typescript-rtti": "^0.9.6"
+    "typescript": "5.0 || 5.1 || 5.3"
+  },
+  "peerDependencies": {
+    "restfuncs-server": ">=2"
   },
   "devDependencies": {
-    "typescript": "5.1.x",
-    "nodemon": "^2.0.15"
+    "@types/ts-expose-internals": "npm:ts-expose-internals@5.3.3",
+    "rimraf": "=5.0.5"
   }
 }

package/readme.md

@@ -1,4 +1,43 @@
-Enhances your classes with [typescript-rtti](), to make them usable with [restfuncs-server](https://www.npmjs.com/package/restfuncs-server). 
-Meaning Restfuncs is able to validate the arguments to your remote methods at runtime.
+# restfuncs-transformer
+This transformer prepares `ServerSession` subclasses for Typia and adds jsDoc info for the (upcoming) API browser.
 
-[Here's how to use it](https://github.com/bogeeee/restfuncs#setting-up-the-build-the-annoying-stuff-)
+## Usage
+[Here's how to use it](https://github.com/bogeeee/restfuncs/tree/3.x/readme.md#setting-up-the-build-here-it-gets-a-bit-nasty-)
+
+
+## How the transformer chain works
+Here is, how the restfuncs-transformer, typia transformer and typescript-rtti work together: 
+1. The `restfuncs-transformer` scans for all `@remote` methods and, at the bottom of inside their class, it adds the following code (here for "myMethod"): 
+````typescript
+
+/**
+ * Code is generated by the restfuncs-transformer during compile-time
+ */
+static getRemoteMethodsMeta(): (typeof this.type_remoteMethodsMeta) {
+    this.__hello_developer__make_sure_your_class_is_a_subclass_of_ServerSession // Give a friendly error message when this is not the case. Otherwise the following statement "const typia = ..." would fail and leaves the user wondering.
+    let typia = this.typiaRuntime; // We need a "typia" defined in the scope, but let restfuncs manage where that dependency comes from
+    return {
+        transformerVersion: {major: XX,  feature: XX },
+        instanceMethods: {
+            "myMethod": {
+                arguments: {
+                    validateEquals: (args: unknown) => typia.validateEquals<Parameters<typeof this.prototype["myMethod"]>>(args),
+                    validatePrune: ...
+                },
+                result: {
+                    validateEquals: (value: unknown) => typia.validateEquals<Awaited<ReturnType<typeof this.prototype["myMethod"]>>>(value),
+                    ...
+                },
+                jsDoc: {
+                    comment: "text with <strong>markup</strong>", 
+                    params: {a: "text..."},
+                    tags: [{name:"returns", comment: "text..."}]
+                }
+            }
+        }
+    }
+}
+````
+
+2. The [Typia transformer](https://typia.io/) will then replace all `typia.validate<T>` expressions with the actual validation code body. Typia calls this "ahead of time validation". At runtime this is used to validate evil input and serialize/deserialize from json/protobuf in an ultra fast way (future).
+3. The [typescript-rtti transformer](https://typescript-rtti.org/) adds type-info decorations for all compiled symbols (that's all this `__RΦ` stuff in the .js). At runtime, this allows restfuncs to easily navigate through- and inspect all the type hierarchy. I.e when mapping REST parameter names to the remote methods arguments, for better error diagnosis, or for the upcoming API browser.

package/transformerUtil.d.ts

@@ -0,0 +1,50 @@
+import ts, { Node, SourceFile, TransformationContext, TransformerFactory } from "typescript";
+type ClassOf<T> = {
+    new (...args: any[]): T;
+};
+/**
+ * Transformerfactory in a better oop style
+ */
+export declare class TransformerFactoryOOP<FT extends FileTransformRun> {
+    transformRunsDone: FT[];
+    fileTransformRunClass: ClassOf<FileTransformRun>;
+    constructor(fileTransformerRunClass: ClassOf<FT>);
+    /**
+     * Transformer for the typescript api (does not offer such a nice oop style)
+     */
+    get asFunction(): TransformerFactory<SourceFile>;
+}
+/**
+ * Stores the context and result of one run. Don't reuse.
+ */
+export declare abstract class FileTransformRun {
+    tsInstance: typeof ts;
+    sourceFile: SourceFile;
+    context: TransformationContext;
+    parentNodes: Node[];
+    used: boolean;
+    constructor(tsInstance: typeof ts, sourceFile: SourceFile, context: TransformationContext);
+    getParent: () => ts.Node;
+    /**
+     * Vistor function
+     * The body must call visitChilds, if the subtree should be visited
+     * @param node
+     */
+    abstract visit(node: Node): Node;
+    protected visitChilds(node: Node): ts.Node;
+    /**
+     * @return text of the node (only for string literals, etc)
+     * @param node
+     */
+    getText(node: Node): string;
+    getChilds(node: Node): ts.Node[];
+    /**
+     *
+     * @param tsInstance
+     * @param node
+     * @param escaped don't know why but sometimes the name can only be read by the escapedText property.
+     */
+    getIdentifierName(node: Node, escaped?: boolean): any;
+}
+export {};
+//# sourceMappingURL=transformerUtil.d.ts.map

package/transformerUtil.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformerUtil.d.ts","sourceRoot":"","sources":["transformerUtil.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAC,IAAI,EAAE,UAAU,EAAc,qBAAqB,EAAE,kBAAkB,EAAC,MAAM,YAAY,CAAC;AAEvG,KAAK,OAAO,CAAC,CAAC,IAAI;IACd,KAAI,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;CACzB,CAAA;AAED;;GAEG;AACH,qBAAa,qBAAqB,CAAC,EAAE,SAAS,gBAAgB;IAC1D,iBAAiB,EAAE,EAAE,EAAE,CAAK;IAC5B,qBAAqB,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;gBAGrC,uBAAuB,EAAE,OAAO,CAAC,EAAE,CAAC;IAIhD;;OAEG;IACH,IAAI,UAAU,IAAI,kBAAkB,CAAC,UAAU,CAAC,CAQ/C;CACJ;AAED;;GAEG;AACH,8BAAsB,gBAAgB;IAClC,UAAU,EAAE,OAAO,EAAE,CAAC;IACtB,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,qBAAqB,CAAC;IAC/B,WAAW,EAAE,IAAI,EAAE,CAAK;IACxB,IAAI,UAAS;gBAED,UAAU,EAAE,OAAO,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,qBAAqB;IAOzF,SAAS,gBAEP;IAEF;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAGhC,SAAS,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI;IAWhC;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM;IAK3B,SAAS,CAAC,IAAI,EAAE,IAAI;IAMpB;;;;;OAKG;IACH,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,UAAQ;CAUhD"}

package/transformerUtil.js

@@ -0,0 +1,104 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileTransformRun = exports.TransformerFactoryOOP = void 0;
+const typescript_1 = __importStar(require("typescript"));
+/**
+ * Transformerfactory in a better oop style
+ */
+class TransformerFactoryOOP {
+    constructor(fileTransformerRunClass) {
+        this.transformRunsDone = [];
+        this.fileTransformRunClass = fileTransformerRunClass;
+    }
+    /**
+     * Transformer for the typescript api (does not offer such a nice oop style)
+     */
+    get asFunction() {
+        return (context) => {
+            return (sourceFile) => {
+                const fileTransformer = new this.fileTransformRunClass(typescript_1.default, sourceFile, context);
+                this.transformRunsDone.push(fileTransformer);
+                return typescript_1.default.visitEachChild(sourceFile, (node) => fileTransformer.visit(node), context);
+            };
+        };
+    }
+}
+exports.TransformerFactoryOOP = TransformerFactoryOOP;
+/**
+ * Stores the context and result of one run. Don't reuse.
+ */
+class FileTransformRun {
+    constructor(tsInstance, sourceFile, context) {
+        this.parentNodes = [];
+        this.used = false;
+        this.getParent = () => {
+            return this.parentNodes[this.parentNodes.length - 1];
+        };
+        this.tsInstance = tsInstance;
+        this.sourceFile = sourceFile;
+        this.context = context;
+    }
+    visitChilds(node) {
+        this.parentNodes.push(node);
+        try {
+            return this.tsInstance.visitEachChild(node, (node) => this.visit(node), this.context);
+        }
+        finally {
+            this.parentNodes.pop();
+        }
+    }
+    /**
+     * @return text of the node (only for string literals, etc)
+     * @param node
+     */
+    getText(node) {
+        // @ts-ignore
+        return node.text;
+    }
+    getChilds(node) {
+        let result = [];
+        this.tsInstance.forEachChild(node, child => result.push(child));
+        return result;
+    }
+    /**
+     *
+     * @param tsInstance
+     * @param node
+     * @param escaped don't know why but sometimes the name can only be read by the escapedText property.
+     */
+    getIdentifierName(node, escaped = false) {
+        const identifierNode = this.getChilds(node).find(child => child.kind == typescript_1.SyntaxKind.Identifier);
+        if (!identifierNode) {
+            throw new Error("Identifier node not found");
+        }
+        if (escaped) {
+            return identifierNode.escapedText;
+        }
+        return identifierNode.getText();
+    }
+}
+exports.FileTransformRun = FileTransformRun;
+//# sourceMappingURL=transformerUtil.js.map

package/transformerUtil.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformerUtil.js","sourceRoot":"","sources":["transformerUtil.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,yDAAuG;AAMvG;;GAEG;AACH,MAAa,qBAAqB;IAK9B,YAAY,uBAAoC;QAJhD,sBAAiB,GAAS,EAAE,CAAA;QAKxB,IAAI,CAAC,qBAAqB,GAAG,uBAAuB,CAAC;IACzD,CAAC;IAED;;OAEG;IACH,IAAI,UAAU;QACV,OAAO,CAAC,OAA8B,EAAE,EAAE;YACtC,OAAO,CAAC,UAAsB,EAAc,EAAE;gBAC1C,MAAM,eAAe,GAAG,IAAI,IAAI,CAAC,qBAAqB,CAAC,oBAAE,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;gBAChF,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,eAAqB,CAAC,CAAC;gBACnD,OAAO,oBAAE,CAAC,cAAc,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;YACzF,CAAC,CAAA;QACL,CAAC,CAAA;IACL,CAAC;CACJ;AArBD,sDAqBC;AAED;;GAEG;AACH,MAAsB,gBAAgB;IAOlC,YAAY,UAAqB,EAAE,UAAsB,EAAE,OAA8B;QAHzF,gBAAW,GAAW,EAAE,CAAA;QACxB,SAAI,GAAG,KAAK,CAAC;QASb,cAAS,GAAG,GAAG,EAAE;YACb,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACzD,CAAC,CAAC;QARE,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;IAeS,WAAW,CAAC,IAAU;QAC5B,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5B,IAAI;YACA,OAAO,IAAI,CAAC,UAAU,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;SACzF;gBAAS;YACN,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC;SAC1B;IACL,CAAC;IAID;;;OAGG;IACH,OAAO,CAAC,IAAU;QACd,aAAa;QACb,OAAO,IAAI,CAAC,IAAI,CAAC;IACrB,CAAC;IAED,SAAS,CAAC,IAAU;QAChB,IAAI,MAAM,GAAW,EAAE,CAAC;QACxB,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAChE,OAAO,MAAM,CAAA;IACjB,CAAC;IAED;;;;;OAKG;IACH,iBAAiB,CAAC,IAAU,EAAE,OAAO,GAAG,KAAK;QACzC,MAAM,cAAc,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,IAAI,uBAAU,CAAC,UAAU,CAAC,CAAC;QAC/F,IAAG,CAAC,cAAc,EAAE;YAChB,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAA;SAC/C;QACD,IAAG,OAAO,EAAE;YACR,OAAQ,cAAsB,CAAC,WAAW,CAAC;SAC9C;QACD,OAAO,cAAc,CAAC,OAAO,EAAE,CAAC;IACpC,CAAC;CACJ;AApED,4CAoEC"}

package/transformerUtil.ts

@@ -0,0 +1,104 @@
+import ts, {Node, SourceFile, SyntaxKind, TransformationContext, TransformerFactory} from "typescript";
+
+type ClassOf<T> = {
+    new(...args: any[]): T
+}
+
+/**
+ * Transformerfactory in a better oop style
+ */
+export class TransformerFactoryOOP<FT extends FileTransformRun> {
+    transformRunsDone: FT[] = []
+    fileTransformRunClass: ClassOf<FileTransformRun>;
+
+
+    constructor(fileTransformerRunClass: ClassOf<FT>) {
+        this.fileTransformRunClass = fileTransformerRunClass;
+    }
+
+    /**
+     * Transformer for the typescript api (does not offer such a nice oop style)
+     */
+    get asFunction(): TransformerFactory<SourceFile> {
+        return (context: TransformationContext) => {
+            return (sourceFile: SourceFile): SourceFile => {
+                const fileTransformer = new this.fileTransformRunClass(ts, sourceFile, context);
+                this.transformRunsDone.push(fileTransformer as FT);
+                return ts.visitEachChild(sourceFile, (node) => fileTransformer.visit(node), context);
+            }
+        }
+    }
+}
+
+/**
+ * Stores the context and result of one run. Don't reuse.
+ */
+export abstract class FileTransformRun {
+    tsInstance: typeof ts;
+    sourceFile: SourceFile
+    context: TransformationContext;
+    parentNodes: Node[] = []
+    used = false;
+
+    constructor(tsInstance: typeof ts, sourceFile: SourceFile, context: TransformationContext) {
+        this.tsInstance = tsInstance;
+        this.sourceFile = sourceFile;
+        this.context = context;
+    }
+
+
+    getParent = () => {
+        return this.parentNodes[this.parentNodes.length - 1];
+    };
+
+    /**
+     * Vistor function
+     * The body must call visitChilds, if the subtree should be visited
+     * @param node
+     */
+    abstract visit(node: Node): Node;
+
+
+    protected visitChilds(node: Node) {
+        this.parentNodes.push(node);
+        try {
+            return this.tsInstance.visitEachChild(node, (node) => this.visit(node), this.context);
+        } finally {
+            this.parentNodes.pop();
+        }
+    }
+
+
+
+    /**
+     * @return text of the node (only for string literals, etc)
+     * @param node
+     */
+    getText(node: Node): string {
+        // @ts-ignore
+        return node.text;
+    }
+
+    getChilds(node: Node) {
+        let result: Node[] = [];
+        this.tsInstance.forEachChild(node, child => result.push(child));
+        return result
+    }
+
+    /**
+     *
+     * @param tsInstance
+     * @param node
+     * @param escaped don't know why but sometimes the name can only be read by the escapedText property.
+     */
+    getIdentifierName(node: Node, escaped = false) {
+        const identifierNode = this.getChilds(node).find(child => child.kind == SyntaxKind.Identifier);
+        if(!identifierNode) {
+            throw new Error("Identifier node not found")
+        }
+        if(escaped) {
+            return (identifierNode as any).escapedText;
+        }
+        return identifierNode.getText();
+    }
+}