@fulcro/transform-core 0.2.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 diguu <rodrigogeribola@hotmail.com>
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# @fulcro/transform-core
+
+Shared machinery behind the Fulcro compile time transformers.
+
+**You do not install this.** `@fulcro/reflect` depends on it, and any other
+package in the library that grows a transformer will too. It is published
+because they depend on it, not because it is meant to be used directly, and its
+shape is theirs to change without notice.
+
+If you are looking for the compiler plugin, it lives in the package whose calls
+it rewrites:
+
+```json
+{ "plugins": [{ "transform": "@fulcro/reflect/transformer" }] }
+```
+
+## Why it exists
+
+The library used to ship one transformer, `@fulcro/transformer`, installed
+beside `@fulcro/reflect` as a peer dependency. Two things were wrong with that.
+
+**It could go missing.** npm installs peer dependencies and Yarn does not, so a
+project could end up with the utilities and no transformer. The failure was
+quiet, because the utilities are built to degrade rather than crash: `defaultOf`
+throws, `nameOf` falls back to parsing closures, `typeOf(…).declared` reads
+`null`. Nothing says _your build is missing a plugin_.
+
+**It could go out of step.** `@fulcro/reflect@0.3` with
+`@fulcro/transformer@0.2` was an installable, broken combination, because what a
+call means and what it compiles to were versioned separately.
+
+Both disappear when the transformer ships inside the package whose calls it
+rewrites. What is left over is the part that belongs to no package in
+particular — and that is this one.
+
+## What is in here
+
+Everything with nothing to do with any particular utility:
+
+| Piece                       | Does                                                                        |
+| --------------------------- | --------------------------------------------------------------------------- |
+| `isOwnedCall`               | Follows a call back to the declaration that owns it, rather than by name    |
+| `createTransformer`         | Walks a source file once and hands each call to the rewriter that claims it |
+| `createFileTransformer`     | Builds and keeps a program, for the bundlers that have no checker           |
+| `createTransformerUnplugin` | The adapter surface Vite, Rollup, Webpack, Rspack, esbuild and Farm expect  |
+
+What lives in each library instead is the part that knows what to **emit** — how
+`defaultOf` fills a tuple, how a type argument becomes a runtime test. That
+split is why a package can own its compile time behaviour without a second
+install, and why two of them can do so without knowing about each other.
+
+## TypeScript 5 and 6 only
+
+```json
+{ "typescript": ">=5.3.3 <7" }
+```
+
+7.x is the native port, and its package no longer exposes the compiler API this
+is built on. Declared as an **optional** peer dependency, so that a project only
+using the runtime half of a library never has to install a compiler it is not
+going to run.
+
+## Licence
+
+ISC.

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared machinery behind the Fulcro compile time transformers.
+ *
+ * **Not a package to depend on directly.** It is installed for you by
+ * `@fulcro/reflect` and `@fulcro/collections`, each of which ships its own
+ * transformer built on this, and its shape is theirs to change.
+ *
+ * What lives here is everything that has nothing to do with any particular
+ * utility: following a call back to the declaration that owns it, walking a
+ * source file once, building and keeping a program for the bundlers that have
+ * no checker of their own, and the adapter surface `unplugin` expects.
+ *
+ * What lives in each library instead is the part that knows what to emit — how
+ * `defaultOf` fills a tuple, how `ofType` turns a type argument into a runtime
+ * test. That split is why a package can own its compile time behaviour without
+ * a second install, and why two of them can do so without knowing about each
+ * other.
+ */
+export { createFileTransformer, type FileTransformer, type TransformCoreOptions, } from './program/index.js';
+export { type CallRewriter, IDENTIFIER_PATTERN, isOwnedCall, isTupleType, type RewriteContext, utilityModuleSegment, } from './shared/index.js';
+export { createTransformer, type TransformerFactory, type TransformerOptions, } from './transformer/index.js';

package/dist/index.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Shared machinery behind the Fulcro compile time transformers.
+ *
+ * **Not a package to depend on directly.** It is installed for you by
+ * `@fulcro/reflect` and `@fulcro/collections`, each of which ships its own
+ * transformer built on this, and its shape is theirs to change.
+ *
+ * What lives here is everything that has nothing to do with any particular
+ * utility: following a call back to the declaration that owns it, walking a
+ * source file once, building and keeping a program for the bundlers that have
+ * no checker of their own, and the adapter surface `unplugin` expects.
+ *
+ * What lives in each library instead is the part that knows what to emit — how
+ * `defaultOf` fills a tuple, how `ofType` turns a type argument into a runtime
+ * test. That split is why a package can own its compile time behaviour without
+ * a second install, and why two of them can do so without knowing about each
+ * other.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTransformer = exports.utilityModuleSegment = exports.isTupleType = exports.isOwnedCall = exports.IDENTIFIER_PATTERN = exports.createFileTransformer = void 0;
+var program_1 = require("./program/index.js");
+Object.defineProperty(exports, "createFileTransformer", { enumerable: true, get: function () { return program_1.createFileTransformer; } });
+var shared_1 = require("./shared/index.js");
+Object.defineProperty(exports, "IDENTIFIER_PATTERN", { enumerable: true, get: function () { return shared_1.IDENTIFIER_PATTERN; } });
+Object.defineProperty(exports, "isOwnedCall", { enumerable: true, get: function () { return shared_1.isOwnedCall; } });
+Object.defineProperty(exports, "isTupleType", { enumerable: true, get: function () { return shared_1.isTupleType; } });
+Object.defineProperty(exports, "utilityModuleSegment", { enumerable: true, get: function () { return shared_1.utilityModuleSegment; } });
+var transformer_1 = require("./transformer/index.js");
+Object.defineProperty(exports, "createTransformer", { enumerable: true, get: function () { return transformer_1.createTransformer; } });

package/dist/program/index.d.ts

@@ -0,0 +1,44 @@
+import { CallRewriter } from '../shared/index.js';
+import { TransformerOptions } from '../transformer/index.js';
+/** Options accepted by the transformer core. */
+export interface TransformCoreOptions extends TransformerOptions {
+    /** Path of the tsconfig driving the program. Defaults to the nearest one. */
+    readonly tsconfig?: string;
+    /** Directory the tsconfig search and the program resolve against. */
+    readonly root?: string;
+}
+/** Transforms one file, or declines it. */
+export interface FileTransformer {
+    /**
+     * Tells whether a file is one this transformer is responsible for.
+     *
+     * Decided from the path alone, because the bundlers that filter before
+     * reading a file have nothing else to offer at that point. Whether the file
+     * actually calls anything is settled later, inside
+     * {@link FileTransformer.transform}.
+     *
+     * @param id Identifier of the file, as the bundler spells it.
+     * @returns `true` when the file is a TypeScript source of the project.
+     */
+    readonly handles: (id: string) => boolean;
+    /**
+     * Applies the transformer to one file.
+     *
+     * @param id Identifier of the file, as the bundler spells it.
+     * @param code Current content of the file.
+     * @returns The rewritten TypeScript, or `null` when nothing was done and the
+     * bundler should keep the original.
+     */
+    readonly transform: (id: string, code: string) => string | null;
+}
+/**
+ * Creates the transformer core.
+ *
+ * The program is built on the first file that actually needs it, so a project
+ * never calling the utilities pays nothing.
+ *
+ * @param rewriters Rewriters of the package this core is serving.
+ * @param options Options of the core.
+ * @returns A transformer usable by any bundler adapter.
+ */
+export declare const createFileTransformer: (rewriters: readonly CallRewriter[], options?: TransformCoreOptions) => FileTransformer;

package/dist/program/index.js

@@ -0,0 +1,269 @@
+"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 () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFileTransformer = void 0;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const typescript_1 = __importDefault(require("typescript"));
+const transformer_1 = require("../transformer/index.js");
+/**
+ * Type checking core shared by every bundler integration.
+ *
+ * The transformer needs a type checker, and no bundler has one: esbuild and swc
+ * reach TypeScript by erasing its types, never by resolving them, so a plugin
+ * cannot simply hand them a transformer and expect `defaultOf<Order>()` to mean
+ * anything. This module therefore builds and keeps its own program, and
+ * transforms each file itself.
+ *
+ * Nothing here knows about any bundler: the adapters built on top only have to
+ * call {@link createFileTransformer} and hand back what it returns. Kept as
+ * CommonJS as well, because the compiler plugin loads it through `require`.
+ */
+/** Extensions carrying TypeScript this core is responsible for. */
+const HANDLED_EXTENSIONS = ['.ts', '.mts', '.cts'];
+/**
+ * Builds the cheap pre-filter that skips files with nothing to rewrite.
+ *
+ * Reading a file is far cheaper than type checking it, so a source mentioning
+ * none of the owned function names never reaches the program. Derived from the
+ * rewriters rather than written out, because each package brings its own names
+ * and this core belongs to none of them.
+ *
+ * @param rewriters Rewriters the core was built with.
+ * @returns A pattern matching any of their function names as a whole word.
+ */
+const buildUtilityPattern = (rewriters) => {
+    const names = rewriters
+        .map((rewriter) => rewriter.functionName)
+        .join('|');
+    return new RegExp(`\\b(${names})\\b`);
+};
+/**
+ * Rewrites a path the way the compiler spells it.
+ *
+ * TypeScript keeps every file name with forward slashes, on every platform,
+ * while the bundler and `path.normalize` hand back the native separator. Mixing
+ * the two silently defeats every lookup against the files of the program: a
+ * file already in it looks new, gets added as another root, and invalidates the
+ * whole program — turning one startup cost into one per file.
+ *
+ * @param fileName Path in whatever spelling it arrived.
+ * @returns The path as the compiler spells it.
+ */
+const toCompilerPath = (fileName) => path.resolve(fileName).split(path.sep).join('/');
+/**
+ * Keeps a TypeScript program alive across recompilations.
+ *
+ * A language service rather than a one shot program: a watch run recompiles the
+ * same files repeatedly, and rebuilding the whole program on each edit would
+ * cost seconds every keystroke. The service reuses everything that did not
+ * change, and the version counters below are what tell it what did.
+ */
+class ProgramHost {
+    /** Files of the program, as resolved from the tsconfig. */
+    rootNames;
+    /** Compiler options resolved from the tsconfig. */
+    options;
+    /** Content handed over by the bundler, which may be ahead of the disk. */
+    overlays = new Map();
+    /** Bumped whenever a file changes, which is how the service invalidates. */
+    versions = new Map();
+    /** Directory the relative paths of the program resolve against. */
+    currentDirectory;
+    /**
+     * Initializes the host from a parsed tsconfig.
+     *
+     * @param parsed Parsed contents of the tsconfig.
+     * @param currentDirectory Directory the program resolves against.
+     */
+    constructor(parsed, currentDirectory) {
+        this.rootNames = parsed.fileNames.map(toCompilerPath);
+        this.options = parsed.options;
+        this.currentDirectory = currentDirectory;
+    }
+    /**
+     * Records the content of a file as the bundler sees it.
+     *
+     * @param fileName File being compiled.
+     * @param content Current content of the file.
+     */
+    update(fileName, content) {
+        if (this.overlays.get(fileName) === content)
+            return;
+        // On a cold run the bundler hands over exactly what is on disk, for
+        // every file of the project. Recording those as changes would
+        // invalidate and re-check the program once per file, turning a single
+        // startup cost into a quadratic one — so an unchanged file is left
+        // alone and stays at the version the program was built with.
+        if (!this.overlays.has(fileName) &&
+            this.rootNames.includes(fileName) &&
+            this.matchesDisk(fileName, content)) {
+            return;
+        }
+        this.overlays.set(fileName, content);
+        this.versions.set(fileName, (this.versions.get(fileName) ?? 0) + 1);
+        // A file the tsconfig never listed — created after startup, or simply
+        // excluded — still has to enter the program to be transformed.
+        if (!this.rootNames.includes(fileName))
+            this.rootNames.push(fileName);
+    }
+    /**
+     * Tells whether the content handed over matches what is on disk.
+     *
+     * @param fileName File being compiled.
+     * @param content Content handed over by the bundler.
+     * @returns `true` when the two are identical.
+     */
+    matchesDisk(fileName, content) {
+        try {
+            return fs.readFileSync(fileName, 'utf8') === content;
+        }
+        catch {
+            return false;
+        }
+    }
+    getScriptFileNames() {
+        return this.rootNames;
+    }
+    getScriptVersion(fileName) {
+        return String(this.versions.get(fileName) ?? 0);
+    }
+    getScriptSnapshot(fileName) {
+        const overlay = this.overlays.get(fileName);
+        if (overlay !== undefined) {
+            return typescript_1.default.ScriptSnapshot.fromString(overlay);
+        }
+        if (!fs.existsSync(fileName))
+            return undefined;
+        return typescript_1.default.ScriptSnapshot.fromString(fs.readFileSync(fileName, 'utf8'));
+    }
+    getCurrentDirectory() {
+        return this.currentDirectory;
+    }
+    getCompilationSettings() {
+        return this.options;
+    }
+    getDefaultLibFileName(options) {
+        return typescript_1.default.getDefaultLibFilePath(options);
+    }
+    readFile(fileName, encoding) {
+        return (this.overlays.get(fileName) ?? typescript_1.default.sys.readFile(fileName, encoding));
+    }
+    fileExists(fileName) {
+        return this.overlays.has(fileName) || typescript_1.default.sys.fileExists(fileName);
+    }
+    readDirectory = typescript_1.default.sys.readDirectory;
+    directoryExists = typescript_1.default.sys.directoryExists;
+    getDirectories = typescript_1.default.sys.getDirectories;
+    realpath = typescript_1.default.sys.realpath;
+}
+/**
+ * Locates and parses the tsconfig driving the program.
+ *
+ * @param root Directory the search starts from.
+ * @param explicit Path given in the options, when there is one.
+ * @returns The parsed tsconfig.
+ * @throws {Error} When no tsconfig can be found or it cannot be read.
+ */
+const parseTsconfig = (root, explicit) => {
+    const configPath = explicit !== undefined
+        ? path.resolve(root, explicit)
+        : typescript_1.default.findConfigFile(root, typescript_1.default.sys.fileExists);
+    if (configPath === undefined) {
+        throw new Error(`No tsconfig.json found from ${root}. The transformer needs one to ` +
+            'know which files belong to the program.');
+    }
+    const read = typescript_1.default.readConfigFile(configPath, typescript_1.default.sys.readFile);
+    if (read.error !== undefined) {
+        throw new Error(typescript_1.default.flattenDiagnosticMessageText(read.error.messageText, '\n'));
+    }
+    return typescript_1.default.parseJsonConfigFileContent(read.config, typescript_1.default.sys, path.dirname(configPath));
+};
+/**
+ * Creates the transformer core.
+ *
+ * The program is built on the first file that actually needs it, so a project
+ * never calling the utilities pays nothing.
+ *
+ * @param rewriters Rewriters of the package this core is serving.
+ * @param options Options of the core.
+ * @returns A transformer usable by any bundler adapter.
+ */
+const createFileTransformer = (rewriters, options = {}) => {
+    const root = options.root ?? process.cwd();
+    const utilityPattern = buildUtilityPattern(rewriters);
+    const transformer = (0, transformer_1.createTransformer)(rewriters);
+    let host;
+    let service;
+    const handles = (id) => {
+        const fileName = id.split('?')[0];
+        if (!HANDLED_EXTENSIONS.includes(path.extname(fileName)))
+            return false;
+        return !fileName.includes('node_modules');
+    };
+    const transform = (id, code) => {
+        if (!handles(id))
+            return null;
+        // Cheap rejection before anything expensive: most files of a project
+        // mention none of the utilities, and building the program for them
+        // would cost seconds for nothing.
+        if (!utilityPattern.test(code))
+            return null;
+        const fileName = toCompilerPath(id.split('?')[0]);
+        if (host === undefined || service === undefined) {
+            host = new ProgramHost(parseTsconfig(root, options.tsconfig), root);
+            service = typescript_1.default.createLanguageService(host, typescript_1.default.createDocumentRegistry());
+        }
+        host.update(fileName, code);
+        const program = service.getProgram();
+        const sourceFile = program?.getSourceFile(fileName);
+        if (program === undefined || sourceFile === undefined)
+            return null;
+        const result = typescript_1.default.transform(sourceFile, [transformer(program, { projectRoot: options.projectRoot ?? root })], program.getCompilerOptions());
+        const [transformed] = result.transformed;
+        const printed = typescript_1.default
+            .createPrinter({ newLine: typescript_1.default.NewLineKind.LineFeed })
+            .printFile(transformed);
+        result.dispose();
+        // Still TypeScript, only with the calls resolved: the bundler goes on to
+        // erase the types as it would have anyway.
+        return printed;
+    };
+    return { handles, transform };
+};
+exports.createFileTransformer = createFileTransformer;

package/dist/shared/index.d.ts

@@ -0,0 +1,84 @@
+import typescript from 'typescript';
+/**
+ * Contract shared by the rewriters of the transformer.
+ *
+ * Each utility owns one module here, so that a change to how `defaultOf` fills
+ * a tuple never has to be made inside the same file that decides how `typeOf`
+ * reports a declaration site. The composition root walks the tree once and asks
+ * each rewriter whether the call in hand belongs to it.
+ */
+/** Everything a rewriter needs from the compilation in progress. */
+export interface RewriteContext {
+    /** Checker of the program being compiled. */
+    readonly checker: typescript.TypeChecker;
+    /** Node factory of the current transformation. */
+    readonly factory: typescript.NodeFactory;
+    /** Root that reported declaration paths are made relative to. */
+    readonly projectRoot: string;
+    /**
+     * Visits a node with the whole transformer.
+     *
+     * Handed over so that a rewriter keeping part of the original call — as
+     * `typeOf` does with its argument — still has the other utilities applied
+     * inside whatever it keeps.
+     */
+    readonly visit: (node: typescript.Node) => typescript.Node;
+}
+/** Rewrites the calls of a single utility. */
+export interface CallRewriter {
+    /** Name the exported function is called by. */
+    readonly functionName: string;
+    /** Path segment identifying the module that declares it. */
+    readonly moduleSegment: string;
+    /**
+     * Rewrites one call.
+     *
+     * @param call Call already known to belong to this rewriter.
+     * @param context Compilation in progress.
+     * @returns The replacement node, or `null` to leave the call untouched so
+     * that the runtime implementation stays in charge.
+     */
+    readonly rewrite: (call: typescript.CallExpression, context: RewriteContext) => typescript.Node | null;
+}
+/** Property names that can be emitted unquoted in an object literal. */
+export declare const IDENTIFIER_PATTERN: RegExp;
+/**
+ * Builds the path segment identifying a utility module.
+ *
+ * These segments tie this package to the folder layout `@fulcro/reflect`
+ * publishes — a call is recognised by the module that declares it, and after
+ * resolution that module is `functions/utils/<name>` inside the built output of
+ * that package. Moving those folders there silently stops the rewriting here,
+ * because a mismatch does not fail loudly on its own: the transformer simply
+ * leaves the calls alone and the runtime fallbacks take over. The compile
+ * fixture is what catches it, and it imports `@fulcro/reflect` by name rather
+ * than by path precisely so that it resolves the same way a consumer would.
+ *
+ * Matched exactly, casing included.
+ *
+ * @param name Folder of the utility inside the output of `@fulcro/reflect`.
+ * @returns The segment to look for in a declaration path.
+ */
+export declare const utilityModuleSegment: (name: string) => string;
+/**
+ * Tells whether a call resolves to the function a rewriter owns.
+ *
+ * The symbol is followed back to its declaration rather than matched by name,
+ * so an unrelated local `nameOf` is never rewritten.
+ *
+ * @param call Call being inspected.
+ * @param checker Checker of the program being compiled.
+ * @param rewriter Rewriter claiming the call.
+ * @returns `true` when the call targets the function of that rewriter.
+ */
+export declare const isOwnedCall: (call: typescript.CallExpression, checker: typescript.TypeChecker, rewriter: CallRewriter) => boolean;
+/**
+ * Tells whether an object type is a tuple.
+ *
+ * Shared because both the description built by `typeOf` and the value built by
+ * `defaultOf` have to tell a tuple apart from a plain array.
+ *
+ * @param type Type being inspected.
+ * @returns `true` when the type is a tuple.
+ */
+export declare const isTupleType: (type: typescript.ObjectType) => boolean;

package/dist/shared/index.js

@@ -0,0 +1,102 @@
+"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 () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTupleType = exports.isOwnedCall = exports.utilityModuleSegment = exports.IDENTIFIER_PATTERN = void 0;
+const path = __importStar(require("node:path"));
+const typescript_1 = __importDefault(require("typescript"));
+/** Property names that can be emitted unquoted in an object literal. */
+exports.IDENTIFIER_PATTERN = /^[A-Za-z_$][\w$]*$/;
+/**
+ * Builds the path segment identifying a utility module.
+ *
+ * These segments tie this package to the folder layout `@fulcro/reflect`
+ * publishes — a call is recognised by the module that declares it, and after
+ * resolution that module is `functions/utils/<name>` inside the built output of
+ * that package. Moving those folders there silently stops the rewriting here,
+ * because a mismatch does not fail loudly on its own: the transformer simply
+ * leaves the calls alone and the runtime fallbacks take over. The compile
+ * fixture is what catches it, and it imports `@fulcro/reflect` by name rather
+ * than by path precisely so that it resolves the same way a consumer would.
+ *
+ * Matched exactly, casing included.
+ *
+ * @param name Folder of the utility inside the output of `@fulcro/reflect`.
+ * @returns The segment to look for in a declaration path.
+ */
+const utilityModuleSegment = (name) => path.join('functions', 'utils', name);
+exports.utilityModuleSegment = utilityModuleSegment;
+/**
+ * Tells whether a call resolves to the function a rewriter owns.
+ *
+ * The symbol is followed back to its declaration rather than matched by name,
+ * so an unrelated local `nameOf` is never rewritten.
+ *
+ * @param call Call being inspected.
+ * @param checker Checker of the program being compiled.
+ * @param rewriter Rewriter claiming the call.
+ * @returns `true` when the call targets the function of that rewriter.
+ */
+const isOwnedCall = (call, checker, rewriter) => {
+    if (!typescript_1.default.isIdentifier(call.expression))
+        return false;
+    if (call.expression.text !== rewriter.functionName)
+        return false;
+    const symbol = checker.getSymbolAtLocation(call.expression);
+    const resolved = symbol !== undefined && (symbol.flags & typescript_1.default.SymbolFlags.Alias) !== 0
+        ? checker.getAliasedSymbol(symbol)
+        : symbol;
+    const declarations = resolved?.declarations ?? [];
+    return declarations.some((declaration) => path
+        .normalize(declaration.getSourceFile().fileName)
+        .includes(rewriter.moduleSegment));
+};
+exports.isOwnedCall = isOwnedCall;
+/**
+ * Tells whether an object type is a tuple.
+ *
+ * Shared because both the description built by `typeOf` and the value built by
+ * `defaultOf` have to tell a tuple apart from a plain array.
+ *
+ * @param type Type being inspected.
+ * @returns `true` when the type is a tuple.
+ */
+const isTupleType = (type) => (type.objectFlags & typescript_1.default.ObjectFlags.Reference) !== 0 &&
+    (type.target.objectFlags &
+        typescript_1.default.ObjectFlags.Tuple) !==
+        0;
+exports.isTupleType = isTupleType;

package/dist/transformer/index.d.ts

@@ -0,0 +1,42 @@
+import typescript from 'typescript';
+import { CallRewriter } from '../shared/index.js';
+/**
+ * Composition root shared by every Fulcro transformer.
+ *
+ * TypeScript erases its own type system on the way to JavaScript: interfaces,
+ * type aliases, generic arguments and the file a type was declared in leave no
+ * trace in the emitted code. A runtime function can therefore only report what
+ * the value in front of it shows, which is why these libraries need a compiler
+ * plugin to answer properly at all.
+ *
+ * This module holds the checker, walks every source file once, and hands each
+ * call to the rewriter that owns it. What any particular utility emits lives in
+ * the package that owns that utility — this one knows only how to walk and how
+ * to ask.
+ *
+ * Which is the whole reason it is a package of its own: `@fulcro/reflect` and
+ * `@fulcro/collections` each ship their own transformer, so neither has to be
+ * installed for the other to work, and neither can drift out of version with
+ * the runtime code it rewrites. The walking is the only part they share.
+ *
+ * Calls no rewriter can resolve are left untouched, so the runtime
+ * implementations stay in charge and a project compiling without the
+ * transformer keeps working, in whatever reduced form each utility documents.
+ */
+/** Options accepted from the `plugins` entry of the tsconfig. */
+export interface TransformerOptions {
+    /** Root the reported declaration paths are made relative to. */
+    readonly projectRoot?: string;
+}
+/** The factory shape `ts-patch` expects from a plugin module. */
+export type TransformerFactory = (program: typescript.Program, options?: TransformerOptions) => typescript.TransformerFactory<typescript.SourceFile>;
+/**
+ * Builds a transformer from a set of rewriters.
+ *
+ * @param rewriters Rewriters consulted for every call, in order. Each one
+ * claims a single exported function of a single module, so the order carries no
+ * meaning beyond the one a reader gives it.
+ * @returns The factory a package exports as the default of its transformer
+ * entry point.
+ */
+export declare const createTransformer: (rewriters: readonly CallRewriter[]) => TransformerFactory;

package/dist/transformer/index.js

@@ -0,0 +1,43 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTransformer = void 0;
+const typescript_1 = __importDefault(require("typescript"));
+const shared_1 = require("../shared/index.js");
+/**
+ * Builds a transformer from a set of rewriters.
+ *
+ * @param rewriters Rewriters consulted for every call, in order. Each one
+ * claims a single exported function of a single module, so the order carries no
+ * meaning beyond the one a reader gives it.
+ * @returns The factory a package exports as the default of its transformer
+ * entry point.
+ */
+const createTransformer = (rewriters) => (program, options = {}) => {
+    const checker = program.getTypeChecker();
+    const projectRoot = options.projectRoot ?? program.getCurrentDirectory();
+    return (context) => {
+        const visit = (node) => {
+            if (typescript_1.default.isCallExpression(node)) {
+                const rewritten = rewriteCall(node);
+                if (rewritten !== null)
+                    return rewritten;
+            }
+            return typescript_1.default.visitEachChild(node, visit, context);
+        };
+        const rewriteContext = {
+            checker,
+            factory: context.factory,
+            projectRoot,
+            visit,
+        };
+        const rewriteCall = (call) => {
+            const owner = rewriters.find((rewriter) => (0, shared_1.isOwnedCall)(call, checker, rewriter));
+            return owner === undefined ? null : owner.rewrite(call, rewriteContext);
+        };
+        return (sourceFile) => typescript_1.default.visitNode(sourceFile, visit);
+    };
+};
+exports.createTransformer = createTransformer;

package/dist/unplugin/index.d.mts

@@ -0,0 +1,57 @@
+import { type UnpluginFactory, type UnpluginInstance } from 'unplugin';
+import { type TransformCoreOptions } from '../program/index.js';
+import { type CallRewriter } from '../shared/index.js';
+/**
+ * Bundler adapters for the Fulcro transformers.
+ *
+ * Built on `unplugin`, so the same integration serves Vite, Rollup, Webpack,
+ * esbuild, Rspack and Farm — and, through them, the frameworks layered on top.
+ * Everything specific to type checking lives in the core this wraps; what is
+ * left here is the shape each bundler expects.
+ *
+ * Nothing here knows which utilities are being rewritten. The owning package
+ * passes its own rewriters in, which is what lets `@fulcro/reflect` and
+ * `@fulcro/collections` each publish a plugin of their own without either
+ * having to know the other exists.
+ *
+ * Emitted as an ES module because `unplugin` ships as one. The core stays
+ * CommonJS, since the compiler plugin loads it through `require`, and an ES
+ * module importing CommonJS is the direction that works.
+ */
+/** Options accepted by every adapter. */
+export type PluginOptions = TransformCoreOptions;
+/**
+ * Every form `unplugin` produces for these options.
+ *
+ * Named through `UnpluginInstance` rather than `ReturnType<typeof
+ * createUnplugin>`, which infers its option type as `unknown` and makes every
+ * adapter below reject the options it is actually given.
+ */
+type Adapters = UnpluginInstance<PluginOptions | undefined>;
+/** The adapters a package re-exports from its own `/unplugin` entry point. */
+export interface TransformerUnplugin {
+    /** The factory itself, for a bundler not covered below. */
+    readonly unpluginFactory: UnpluginFactory<PluginOptions | undefined>;
+    /** Adapter for Vite, which is also what vitest runs on. */
+    readonly vite: Adapters['vite'];
+    /** Adapter for Rollup. */
+    readonly rollup: Adapters['rollup'];
+    /** Adapter for Webpack. */
+    readonly webpack: Adapters['webpack'];
+    /** Adapter for Rspack. */
+    readonly rspack: Adapters['rspack'];
+    /** Adapter for esbuild. */
+    readonly esbuild: Adapters['esbuild'];
+    /** Adapter for Farm. */
+    readonly farm: Adapters['farm'];
+}
+/**
+ * Builds the bundler adapters for one set of rewriters.
+ *
+ * @param rewriters Rewriters of the package publishing the plugin.
+ * @param name Name the plugin reports to the bundler, which is what shows up
+ * in its logs and timings.
+ * @returns Every adapter `unplugin` can produce.
+ */
+export declare const createTransformerUnplugin: (rewriters: readonly CallRewriter[], name: string) => TransformerUnplugin;
+export {};

package/dist/unplugin/index.mjs

@@ -0,0 +1,61 @@
+import { createUnplugin, } from 'unplugin';
+import { createFileTransformer, } from '../program/index.js';
+/**
+ * Builds the bundler adapters for one set of rewriters.
+ *
+ * @param rewriters Rewriters of the package publishing the plugin.
+ * @param name Name the plugin reports to the bundler, which is what shows up
+ * in its logs and timings.
+ * @returns Every adapter `unplugin` can produce.
+ */
+export const createTransformerUnplugin = (rewriters, name) => {
+    const unpluginFactory = (options = {}) => {
+        let transformer;
+        /**
+         * Resolves the core lazily, so that the root reported by the bundler is
+         * already known when the program is configured.
+         *
+         * @returns The transformer core.
+         */
+        const resolve = () => {
+            transformer ??= createFileTransformer(rewriters, options);
+            return transformer;
+        };
+        return {
+            name,
+            // Ahead of the TypeScript handling of the bundler: once esbuild or swc
+            // has erased the types, there is nothing left for the transformer to
+            // read.
+            enforce: 'pre',
+            transformInclude(id) {
+                return resolve().handles(id);
+            },
+            transform(code, id) {
+                const transformed = resolve().transform(id, code);
+                return transformed === null ? null : { code: transformed, map: null };
+            },
+            vite: {
+                configResolved(config) {
+                    // The root of the bundler wins over the working directory, which
+                    // is what makes the plugin behave inside a monorepo.
+                    if (config.root !== undefined && options.root === undefined) {
+                        transformer = createFileTransformer(rewriters, {
+                            ...options,
+                            root: config.root,
+                        });
+                    }
+                },
+            },
+        };
+    };
+    const unplugin = createUnplugin(unpluginFactory);
+    return {
+        unpluginFactory,
+        vite: unplugin.vite,
+        rollup: unplugin.rollup,
+        webpack: unplugin.webpack,
+        rspack: unplugin.rspack,
+        esbuild: unplugin.esbuild,
+        farm: unplugin.farm,
+    };
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+	"name": "@fulcro/transform-core",
+	"version": "0.2.1",
+	"description": "Shared machinery behind the Fulcro compile time transformers. Installed for you; not meant to be depended on directly.",
+	"keywords": [
+		"typescript",
+		"transformer",
+		"ts-patch",
+		"unplugin",
+		"compiler"
+	],
+	"license": "ISC",
+	"author": "diguu <rodrigogeribola@hotmail.com>",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./unplugin": {
+			"types": "./dist/unplugin/index.d.mts",
+			"default": "./dist/unplugin/index.mjs"
+		},
+		"./package.json": "./package.json"
+	},
+	"files": [
+		"dist"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+		"typecheck": "tsc --noEmit -p tsconfig.json",
+		"prepublishOnly": "npm run build"
+	},
+	"dependencies": {
+		"unplugin": "^3.3.0"
+	},
+	"peerDependencies": {
+		"typescript": ">=5.3.3 <7"
+	},
+	"peerDependenciesMeta": {
+		"typescript": {
+			"optional": true
+		}
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"engines": {
+		"node": ">=22"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/DigUu-RL/fulcro.git",
+		"directory": "packages/transform-core"
+	},
+	"homepage": "https://github.com/DigUu-RL/fulcro/tree/main/packages/transform-core#readme",
+	"bugs": {
+		"url": "https://github.com/DigUu-RL/fulcro/issues"
+	}
+}