@typed/virtual-modules 1.0.0-beta.1

package/dist/NodeModulePluginLoader.js

@@ -0,0 +1,175 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
+import { runInThisContext } from "node:vm";
+import { pathIsUnderBase } from "./internal/path.js";
+import { sanitizeErrorMessage } from "./internal/sanitize.js";
+const toMessage = (error) => {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+};
+const isPluginLike = (value) => {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.name === "string" &&
+        typeof candidate.shouldResolve === "function" &&
+        typeof candidate.build === "function");
+};
+const invalidPluginError = (request, message) => ({
+    status: "error",
+    specifier: request.specifier,
+    baseDir: request.baseDir,
+    code: "invalid-plugin-export",
+    message,
+});
+const loadFailedError = (request, message) => ({
+    status: "error",
+    specifier: request.specifier,
+    baseDir: request.baseDir,
+    code: "module-load-failed",
+    message,
+});
+const notFoundError = (request, message) => ({
+    status: "error",
+    specifier: request.specifier,
+    baseDir: request.baseDir,
+    code: "module-not-found",
+    message,
+});
+const pathEscapesError = (request, message) => ({
+    status: "error",
+    specifier: request.specifier,
+    baseDir: request.baseDir,
+    code: "path-escapes-base",
+    message,
+});
+const MAX_PATH_LENGTH = 4096;
+const invalidRequestError = (message) => ({
+    status: "error",
+    specifier: "",
+    baseDir: "",
+    code: "invalid-request",
+    message,
+});
+const getErrorCode = (error) => typeof error === "object" && error !== null && "code" in error
+    ? String(error.code)
+    : undefined;
+export class NodeModulePluginLoader {
+    load(input) {
+        if (isPluginLike(input)) {
+            return {
+                status: "loaded",
+                plugin: input,
+                resolvedPath: "<preloaded>",
+            };
+        }
+        const request = input;
+        if (typeof request.baseDir !== "string" || request.baseDir.trim() === "") {
+            return invalidRequestError("baseDir must be a non-empty string");
+        }
+        if (typeof request.specifier !== "string" || request.specifier.trim() === "") {
+            return invalidRequestError("specifier must be a non-empty string");
+        }
+        if (request.baseDir.length > MAX_PATH_LENGTH || request.specifier.length > MAX_PATH_LENGTH) {
+            return invalidRequestError(`baseDir and specifier must be at most ${MAX_PATH_LENGTH} characters`);
+        }
+        const require = createRequire(resolve(request.baseDir, "__typed_virtual_modules_loader__.cjs"));
+        let resolvedPath;
+        try {
+            resolvedPath = require.resolve(request.specifier, { paths: [request.baseDir] });
+        }
+        catch (error) {
+            return notFoundError(request, `Could not resolve plugin "${request.specifier}" from "${request.baseDir}": ${sanitizeErrorMessage(toMessage(error))}`);
+        }
+        if (!pathIsUnderBase(request.baseDir, resolvedPath)) {
+            return pathEscapesError(request, sanitizeErrorMessage(`Resolved plugin path "${resolvedPath}" is not under baseDir "${request.baseDir}"`));
+        }
+        let mod;
+        try {
+            mod = require(resolvedPath);
+        }
+        catch (error) {
+            const errorCode = getErrorCode(error);
+            if (errorCode === "ERR_REQUIRE_ASYNC_MODULE") {
+                return loadFailedError(request, sanitizeErrorMessage(`Could not load plugin module "${resolvedPath}": plugin module uses top-level await and cannot be loaded synchronously`));
+            }
+            if (errorCode === "ERR_REQUIRE_ESM") {
+                const esmFallback = this.#loadSyncEsmModule(resolvedPath, require);
+                if (esmFallback.status === "loaded") {
+                    mod = esmFallback.moduleExport;
+                }
+                else {
+                    return loadFailedError(request, esmFallback.message);
+                }
+            }
+            else {
+                return loadFailedError(request, `Could not load plugin module "${resolvedPath}": ${sanitizeErrorMessage(toMessage(error))}`);
+            }
+        }
+        const normalizedPlugin = this.#normalizeModuleExport(mod);
+        if (!normalizedPlugin) {
+            return invalidPluginError(request, sanitizeErrorMessage(`Resolved module "${resolvedPath}" does not export a valid VirtualModulePlugin`));
+        }
+        return {
+            status: "loaded",
+            plugin: normalizedPlugin,
+            resolvedPath,
+        };
+    }
+    loadMany(inputs) {
+        return inputs.map((input) => this.load(input));
+    }
+    #loadSyncEsmModule(resolvedPath, localRequire) {
+        let tsMod;
+        try {
+            tsMod = localRequire("typescript");
+        }
+        catch (error) {
+            return loadFailedError({ specifier: resolvedPath, baseDir: dirname(resolvedPath) }, sanitizeErrorMessage(`Could not load sync ESM plugin "${resolvedPath}": failed to load TypeScript for transpilation: ${toMessage(error)}`));
+        }
+        try {
+            const sourceText = readFileSync(resolvedPath, "utf8");
+            const transpiled = tsMod.transpileModule(sourceText, {
+                fileName: resolvedPath,
+                compilerOptions: {
+                    module: tsMod.ModuleKind.CommonJS,
+                    target: tsMod.ScriptTarget.ES2020,
+                    moduleResolution: tsMod.ModuleResolutionKind.NodeNext,
+                    esModuleInterop: true,
+                    allowSyntheticDefaultImports: true,
+                },
+                reportDiagnostics: false,
+            }).outputText;
+            const module = { exports: {} };
+            const evaluate = runInThisContext(`(function (exports, require, module, __filename, __dirname) {${transpiled}\n})`, { filename: resolvedPath });
+            evaluate(module.exports, localRequire, module, resolvedPath, dirname(resolvedPath));
+            return { status: "loaded", moduleExport: module.exports };
+        }
+        catch (error) {
+            return {
+                status: "error",
+                message: sanitizeErrorMessage(`Could not load sync ESM plugin "${resolvedPath}": ${toMessage(error)}`),
+            };
+        }
+    }
+    #normalizeModuleExport(mod) {
+        if (isPluginLike(mod)) {
+            return mod;
+        }
+        if (!mod || typeof mod !== "object") {
+            return undefined;
+        }
+        const candidate = mod;
+        if (isPluginLike(candidate.default)) {
+            return candidate.default;
+        }
+        if (isPluginLike(candidate.plugin)) {
+            return candidate.plugin;
+        }
+        return undefined;
+    }
+}

package/dist/PluginManager.d.ts

@@ -0,0 +1,10 @@
+import type { ResolveVirtualModuleOptions, VirtualModulePlugin, VirtualModuleResolution, VirtualModuleResolver } from "./types.js";
+export declare class PluginManager implements VirtualModuleResolver {
+    #private;
+    constructor(plugins?: readonly VirtualModulePlugin[]);
+    get plugins(): readonly VirtualModulePlugin[];
+    register(plugin: VirtualModulePlugin): void;
+    registerMany(plugins: readonly VirtualModulePlugin[]): void;
+    resolveModule(options: ResolveVirtualModuleOptions): VirtualModuleResolution;
+}
+//# sourceMappingURL=PluginManager.d.ts.map

package/dist/PluginManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginManager.d.ts","sourceRoot":"","sources":["../src/PluginManager.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,2BAA2B,EAK3B,mBAAmB,EACnB,uBAAuB,EACvB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAwCpB,qBAAa,aAAc,YAAW,qBAAqB;;gBAG7C,OAAO,GAAE,SAAS,mBAAmB,EAAO;IAIxD,IAAI,OAAO,IAAI,SAAS,mBAAmB,EAAE,CAE5C;IAED,QAAQ,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI;IAI3C,YAAY,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,GAAG,IAAI;IAM3D,aAAa,CAAC,OAAO,EAAE,2BAA2B,GAAG,uBAAuB;CAiJ7E"}

package/dist/PluginManager.js

@@ -0,0 +1,151 @@
+import { sanitizeErrorMessage } from "./internal/sanitize.js";
+import { validateNonEmptyString } from "./internal/validation.js";
+import { isVirtualModuleBuildError, isVirtualModuleBuildSuccess, } from "./types.js";
+/**
+ * TypeInfoApi used when createTypeInfoApiSession is not provided.
+ * Returns safe defaults instead of throwing.
+ * Hosts should always supply createTypeInfoApiSession when plugins use api.file(), api.directory(), or api.resolveExport() for correct behavior.
+ */
+const noopTypeInfoApi = {
+    file: () => ({ ok: false, error: "invalid-input" }),
+    directory: () => [],
+    resolveExport: () => undefined,
+    isAssignableTo: () => false,
+};
+const noopSession = {
+    api: noopTypeInfoApi,
+    consumeDependencies: () => [],
+};
+const toMessage = (error) => {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+};
+const createDiagnostic = (code, pluginName, message) => ({
+    code,
+    pluginName,
+    message,
+});
+export class PluginManager {
+    #plugins;
+    constructor(plugins = []) {
+        this.#plugins = [...plugins];
+    }
+    get plugins() {
+        return this.#plugins;
+    }
+    register(plugin) {
+        this.#plugins.push(plugin);
+    }
+    registerMany(plugins) {
+        for (const plugin of plugins) {
+            this.register(plugin);
+        }
+    }
+    resolveModule(options) {
+        const idResult = validateNonEmptyString(options.id, "options.id");
+        if (!idResult.ok) {
+            return {
+                status: "error",
+                diagnostic: createDiagnostic("invalid-options", "", idResult.reason),
+            };
+        }
+        const importerResult = validateNonEmptyString(options.importer, "options.importer");
+        if (!importerResult.ok) {
+            return {
+                status: "error",
+                diagnostic: createDiagnostic("invalid-options", "", importerResult.reason),
+            };
+        }
+        const createSession = options.createTypeInfoApiSession;
+        for (const plugin of this.#plugins) {
+            const nameResult = validateNonEmptyString(plugin.name, "Plugin name");
+            if (!nameResult.ok) {
+                return {
+                    status: "error",
+                    diagnostic: createDiagnostic("invalid-options", "", nameResult.reason),
+                };
+            }
+            const shouldResolve = this.#safeShouldResolve(plugin, options.id, options.importer);
+            if (shouldResolve.status === "error") {
+                return shouldResolve;
+            }
+            if (!shouldResolve.value) {
+                continue;
+            }
+            let session;
+            try {
+                session = createSession?.({ id: options.id, importer: options.importer }) ?? noopSession;
+            }
+            catch (error) {
+                const msg = toMessage(error);
+                // Treat temporary unavailability (e.g. program not loaded) as unresolved so retry can succeed later.
+                if (msg.includes("Program not yet available") ||
+                    msg.includes("TypeInfo session creation failed")) {
+                    continue;
+                }
+                return {
+                    status: "error",
+                    diagnostic: createDiagnostic("session-creation-failed", plugin.name, `Session creation failed: ${sanitizeErrorMessage(msg)}`),
+                };
+            }
+            try {
+                const result = plugin.build(options.id, options.importer, session.api);
+                if (typeof result === "string") {
+                    return {
+                        status: "resolved",
+                        pluginName: plugin.name,
+                        sourceText: result,
+                        dependencies: session.consumeDependencies(),
+                    };
+                }
+                if (isVirtualModuleBuildError(result)) {
+                    const first = result.errors[0];
+                    const diagnostic = first &&
+                        typeof first === "object" &&
+                        typeof first.code === "string" &&
+                        typeof first.message === "string" &&
+                        typeof first.pluginName === "string"
+                        ? first
+                        : createDiagnostic("invalid-build-output", plugin.name, `Plugin "${plugin.name}" returned errors with invalid diagnostic shape`);
+                    return { status: "error", diagnostic };
+                }
+                if (isVirtualModuleBuildSuccess(result)) {
+                    return {
+                        status: "resolved",
+                        pluginName: plugin.name,
+                        sourceText: result.sourceText,
+                        dependencies: session.consumeDependencies(),
+                        ...(result.warnings?.length ? { warnings: result.warnings } : {}),
+                    };
+                }
+                return {
+                    status: "error",
+                    diagnostic: createDiagnostic("invalid-build-output", plugin.name, `Plugin "${plugin.name}" returned a non-string build result`),
+                };
+            }
+            catch (error) {
+                return {
+                    status: "error",
+                    diagnostic: createDiagnostic("plugin-build-threw", plugin.name, `Plugin "${plugin.name}" build failed: ${sanitizeErrorMessage(toMessage(error))}`),
+                };
+            }
+        }
+        return { status: "unresolved" };
+    }
+    #safeShouldResolve(plugin, id, importer) {
+        try {
+            return {
+                status: "ok",
+                value: plugin.shouldResolve(id, importer),
+            };
+        }
+        catch (error) {
+            return {
+                status: "error",
+                diagnostic: createDiagnostic("plugin-should-resolve-threw", plugin.name, `Plugin "${plugin.name}" shouldResolve failed: ${sanitizeErrorMessage(toMessage(error))}`),
+            };
+        }
+    }
+}

package/dist/TypeInfoApi.d.ts

@@ -0,0 +1,71 @@
+import type * as ts from "typescript";
+import { type CreateTypeInfoApiSession, type TypeInfoApiSession } from "./types.js";
+import type { TypeNode, TypeTargetSpec } from "./types.js";
+/**
+ * Pre-resolved type for structural assignability checks.
+ * Host resolves ts.Type from the program (e.g. Fx from @typed/fx) and passes it.
+ */
+export interface ResolvedTypeTarget {
+    readonly id: string;
+    readonly type: ts.Type;
+}
+export interface CreateTypeInfoApiSessionOptions {
+    readonly ts: typeof import("typescript");
+    readonly program: ts.Program;
+    readonly maxTypeDepth?: number;
+    /** Pre-resolved types for assignability checks. Takes precedence over typeTargetSpecs when both exist. */
+    readonly typeTargets?: readonly ResolvedTypeTarget[];
+    /**
+     * Specs to resolve from program imports for assignability checks.
+     * Resolution happens internally; use this instead of typeTargets when you have module+export specs.
+     */
+    readonly typeTargetSpecs?: readonly TypeTargetSpec[];
+    /**
+     * When true (default) and typeTargetSpecs are provided but resolution finds zero targets,
+     * session creation throws. Set false to allow empty resolution (assignableTo will be undefined for all exports).
+     */
+    readonly failWhenNoTargetsResolved?: boolean;
+    /**
+     * Assignability check mode.
+     * - "strict": Use only checker.isTypeAssignableTo; no heuristic fallbacks. Correct TS semantics.
+     * - "compatibility" (default): Use checker.isTypeAssignableTo first, then fallbacks for generic/inheritance
+     *   when types come from different files (e.g. fixture vs bootstrap). Union sources require ALL
+     *   constituents to be assignable (sound union semantics).
+     */
+    readonly assignabilityMode?: "strict" | "compatibility";
+    /**
+     * Optional callback when an internal TS API or fallback path catches an error.
+     * Assignability and serialization may degrade (e.g. "not assignable" or safe fallback) without throwing.
+     * Use for observability in production; default behavior is unchanged when not provided.
+     */
+    readonly onInternalError?: (err: unknown, context: string) => void;
+}
+/**
+ * Serialize a TypeScript type to TypeNode. For testing serializer branches (typeOperator, enum, etc).
+ * @internal
+ */
+export declare function serializeTypeForTest(type: ts.Type, checker: ts.TypeChecker, tsMod: typeof import("typescript"), maxDepth?: number): TypeNode;
+/**
+ * Generate bootstrap file content that imports all modules from typeTargetSpecs.
+ * Include this file in the program's rootNames so resolveTypeTargetsFromSpecs can
+ * find types without requiring user source to import them.
+ *
+ * @example
+ * ```ts
+ * const bootstrapContent = createTypeTargetBootstrapContent(HTTPAPI_TYPE_TARGET_SPECS);
+ * const bootstrapPath = join(tmpDir, "__typeTargetBootstrap.ts");
+ * writeFileSync(bootstrapPath, bootstrapContent);
+ * const program = ts.createProgram([...rootFiles, bootstrapPath], options, host);
+ * ```
+ */
+export declare function createTypeTargetBootstrapContent(specs: readonly TypeTargetSpec[]): string;
+/**
+ * Resolve type targets from program imports using the given specs.
+ * Scans source files for imports from the specified modules and extracts types.
+ * Requires the program to include files that import from these modules (e.g.
+ * use createTypeTargetBootstrapContent and add to rootNames).
+ */
+export declare function resolveTypeTargetsFromSpecs(program: ts.Program, tsMod: typeof import("typescript"), specs: readonly TypeTargetSpec[]): ResolvedTypeTarget[];
+export declare const createTypeInfoApiSession: (options: CreateTypeInfoApiSessionOptions) => TypeInfoApiSession;
+export declare const createTypeInfoApiSessionFactory: (options: CreateTypeInfoApiSessionOptions) => CreateTypeInfoApiSession;
+//# sourceMappingURL=TypeInfoApi.d.ts.map

package/dist/TypeInfoApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TypeInfoApi.d.ts","sourceRoot":"","sources":["../src/TypeInfoApi.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EACL,KAAK,wBAAwB,EAI7B,KAAK,kBAAkB,EAKxB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAsBV,QAAQ,EAGR,cAAc,EAGf,MAAM,YAAY,CAAC;AAsBpB;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,EAAE,EAAE,cAAc,YAAY,CAAC,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,0GAA0G;IAC1G,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACrD;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IACrD;;;OAGG;IACH,QAAQ,CAAC,yBAAyB,CAAC,EAAE,OAAO,CAAC;IAC7C;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,QAAQ,GAAG,eAAe,CAAC;IACxD;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACpE;AAkbD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,OAAO,EAAE,EAAE,CAAC,WAAW,EACvB,KAAK,EAAE,cAAc,YAAY,CAAC,EAClC,QAAQ,SAAI,GACX,QAAQ,CAEV;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,SAAS,cAAc,EAAE,GAC/B,MAAM,CAkBR;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,EAAE,CAAC,OAAO,EACnB,KAAK,EAAE,cAAc,YAAY,CAAC,EAClC,KAAK,EAAE,SAAS,cAAc,EAAE,GAC/B,kBAAkB,EAAE,CAsHtB;AA0RD,eAAO,MAAM,wBAAwB,GACnC,SAAS,+BAA+B,KACvC,kBAkOF,CAAC;AAEF,eAAO,MAAM,+BAA+B,GACzC,SAAS,+BAA+B,KAAG,wBAET,CAAC"}