type-registry-effect 0.1.0

package/node.d.ts

@@ -0,0 +1,890 @@
+/**
+ * type-registry-effect/node — Node.js platform layer and Promise convenience API.
+ *
+ * @remarks
+ * This entry point provides {@link NodeLayer}, a fully-closed Effect layer that
+ * composes {@link TypeRegistryLive} with `NodeFileSystem` and `NodeHttpClient`
+ * from `@effect/platform-node`. It also re-exports every {@link TypeRegistry}
+ * namespace function as a plain `Promise`-returning wrapper so consumers who do
+ * not use Effect directly can call `await fetchAndCache(pkg)` without managing
+ * layers.
+ *
+ * Install the optional peer dependency before importing this entry point:
+ *
+ * ```bash
+ * npm install @effect/platform-node
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import { TypeRegistry, PackageSpec } from "type-registry-effect";
+ * import { NodeLayer } from "type-registry-effect/node";
+ *
+ * const program = TypeRegistry.getVFS([
+ *   new PackageSpec({ name: "zod", version: "3.23.8" }),
+ * ]);
+ *
+ * const vfs = await Effect.runPromise(Effect.provide(program, NodeLayer));
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { PackageSpec } from "type-registry-effect";
+ * import { fetchAndCache, getVFS } from "type-registry-effect/node";
+ *
+ * const pkg = new PackageSpec({ name: "zod", version: "3.23.8" });
+ * await fetchAndCache(pkg);
+ * const vfs = await getVFS([pkg]);
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import { Context } from 'effect';
+import type { Effect } from 'effect';
+import { Equals } from 'effect/Types';
+import { Layer } from 'effect';
+import { Schema } from 'effect';
+import * as ts from 'typescript';
+import { VirtualTypeScriptEnvironment } from '@typescript/vfs';
+import { YieldableError } from 'effect/Cause';
+
+/**
+ * Raised when a disk cache operation (read, write, delete, or list) fails.
+ *
+ * @remarks
+ * The `operation` field indicates which cache operation triggered the failure,
+ * `path` is the filesystem path involved, and `message` describes the
+ * underlying cause (e.g. permission denied, disk full). Use `Effect.catchTag`
+ * with the `"CacheError"` tag to handle this error selectively.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import type { CacheError } from "type-registry-effect";
+ * import { TypeRegistry, PackageSpec } from "type-registry-effect";
+ * import { NodeLayer } from "type-registry-effect/node";
+ *
+ * const program = TypeRegistry.fetchAndCache(
+ *   new PackageSpec({ name: "zod", version: "3.23.8" }),
+ * ).pipe(
+ *   Effect.catchTag("CacheError", (err: CacheError) =>
+ *     Effect.logWarning(`Cache ${err.operation} failed at ${err.path}: ${err.message}`),
+ *   ),
+ * );
+ *
+ * await Effect.runPromise(Effect.provide(program, NodeLayer));
+ * ```
+ *
+ * @see {@link CacheService}
+ * @public
+ */
+export declare class CacheError extends CacheErrorBase<{
+    readonly operation: "read" | "write" | "delete" | "list";
+    readonly path: string;
+    readonly message: string;
+}> {
+}
+
+/**
+ * @internal
+ * Exported for declaration bundling (api-extractor). When `export *` re-exports
+ * a class whose `extends` expression is an inline call like
+ * `Data.TaggedError(...)`, TypeScript emits an un-nameable `_base` symbol in
+ * the declaration file. Splitting the base into a named export gives the
+ * bundler a stable reference.
+ *
+ * @privateRemarks
+ * This base constant must remain a named export so that api-extractor can
+ * resolve the extends clause of {@link CacheError} to a stable
+ * declaration. Without it the bundled `.d.ts` would contain an anonymous
+ * `_base` symbol that cannot be referenced by downstream consumers.
+ */
+export declare const CacheErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
+    readonly _tag: "CacheError";
+} & Readonly<A>;
+
+/**
+ * Metadata stored alongside cached packages on disk.
+ *
+ * @remarks
+ * Each cached package directory contains a metadata file recording when it was
+ * cached and the version that was resolved. The optional `ttl` field (in
+ * milliseconds) allows per-package cache expiration policies. When `ttl` is
+ * omitted the cache entry never expires automatically.
+ *
+ * @example
+ * ```typescript
+ * import { CacheMetadata } from "type-registry-effect";
+ *
+ * // Metadata with an explicit 1-hour TTL
+ * const meta: CacheMetadata = {
+ *   version: "3.23.8",
+ *   cachedAt: Date.now(),
+ *   ttl: 60 * 60 * 1000,
+ * };
+ *
+ * // Metadata that never expires
+ * const permanent: CacheMetadata = {
+ *   version: "5.4.2",
+ *   cachedAt: Date.now(),
+ * };
+ * ```
+ *
+ * @see {@link CacheServiceLive}
+ * @see {@link TypeRegistry.fetchAndCache}
+ * @public
+ */
+export declare interface CacheMetadata {
+    readonly version: string;
+    readonly cachedAt: number;
+    readonly ttl?: number | undefined;
+}
+
+/**
+ * Effect Schema for validating and encoding {@link CacheMetadata}.
+ *
+ * @see {@link CacheMetadata}
+ */
+export declare const CacheMetadata: Schema.Schema<CacheMetadata>;
+
+/**
+ * Effect service interface for the disk-based type definition cache.
+ *
+ * @remarks
+ * Implementations store type definition files and metadata on disk using a
+ * platform-specific {@link @effect/platform#FileSystem | FileSystem} service.
+ * Platform dependencies are resolved **within the layer**, so consumers of this
+ * interface never interact with the filesystem directly.
+ *
+ * Use this tag to access cache methods inside an `Effect.gen` block. The live
+ * implementation is provided by {@link CacheServiceLive} (or the lower-level
+ * {@link makeNodeCacheLayer}).
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import { CacheService } from "type-registry-effect";
+ * import type { PackageSpec } from "type-registry-effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const cache = yield* CacheService;
+ *   const exists = yield* cache.exists({ name: "lodash", version: "4.17.21" } as PackageSpec);
+ *   console.log("cached:", exists);
+ * });
+ * ```
+ *
+ * @see {@link CacheServiceLive}
+ * @see {@link makeNodeCacheLayer}
+ *
+ * @public
+ */
+export declare interface CacheService {
+    /** Check whether cached type definitions exist for a package. */
+    readonly exists: (pkg: PackageSpec) => Effect.Effect<boolean, CacheError>;
+    /** Read a single cached file by relative path within the package cache directory. */
+    readonly read: (pkg: PackageSpec, filePath: string) => Effect.Effect<string, CacheError>;
+    /** Write a single file into the package cache directory, creating parent directories as needed. */
+    readonly write: (pkg: PackageSpec, filePath: string, content: string) => Effect.Effect<void, CacheError>;
+    /** List all cached file paths (relative) for a package. */
+    readonly listFiles: (pkg: PackageSpec) => Effect.Effect<ReadonlyArray<string>, CacheError>;
+    /** Read the `.metadata.json` sidecar for a cached package. */
+    readonly readMetadata: (pkg: PackageSpec) => Effect.Effect<CacheMetadata, CacheError>;
+    /** Write or overwrite the `.metadata.json` sidecar for a cached package. */
+    readonly writeMetadata: (pkg: PackageSpec, metadata: CacheMetadata) => Effect.Effect<void, CacheError>;
+    /** Build a {@link VirtualFileSystem} from the cache, suitable for an in-memory TS compiler host. */
+    readonly getVFS: (pkg: PackageSpec) => Effect.Effect<VirtualFileSystem, CacheError>;
+    /** Remove all cached data for a package, including metadata. */
+    readonly remove: (pkg: PackageSpec) => Effect.Effect<void, CacheError>;
+}
+
+/**
+ * Effect Context tag for the {@link CacheService} service.
+ *
+ * @see {@link CacheServiceLive}
+ * @see {@link makeNodeCacheLayer}
+ */
+export declare const CacheService: Context.Tag<CacheService, CacheService>;
+
+/**
+ * Create a TypeScript virtual environment cache for use with Twoslash
+ * or other TypeScript language service consumers (Promise API).
+ */
+export declare const createTypeScriptCache: (packages: readonly PackageSpec[], compilerOptions: ts.CompilerOptions) => Promise<Map<string, VirtualTypeScriptEnvironment>>;
+
+/**
+ * Fetch and cache a package's type definitions (Promise API).
+ */
+export declare const fetchAndCache: (pkg: PackageSpec, options?: {
+    readonly ttl?: number;
+} | undefined) => Promise<void>;
+
+/**
+ * Schema for the jsDelivr flat file tree API response.
+ *
+ * @remarks
+ * The response includes a `default` field indicating the package's default
+ * branch/tag and a `files` array of {@link FileTreeEntry} objects. This
+ * corresponds to the `GET /v1/packages/npm/:package@:version/flat` endpoint.
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { FileTreeResponse } from "type-registry-effect";
+ *
+ * const decode = Schema.decodeUnknownSync(FileTreeResponse);
+ * const tree = decode({
+ *   default: "/dist/index.js",
+ *   files: [
+ *     { name: "/dist/index.js", hash: "abc123", time: "2024-01-15T10:30:00.000Z", size: 2048 },
+ *     { name: "/dist/index.d.ts", hash: "def456", time: "2024-01-15T10:30:00.000Z", size: 4096 },
+ *   ],
+ * });
+ * ```
+ *
+ * @see {@link PackageFetcher.getFileTree}
+ * @see {@link https://www.jsdelivr.com/docs/data.jsdelivr.com | jsDelivr Data API}
+ * @public
+ */
+export declare const FileTreeResponse: Schema.Struct<{
+    default: typeof Schema.String;
+    files: Schema.Array$<Schema.Struct<{
+        name: typeof Schema.String;
+        hash: typeof Schema.String;
+        time: typeof Schema.String;
+        size: typeof Schema.Number;
+    }>>;
+}>;
+
+export declare type FileTreeResponse = Schema.Schema.Type<typeof FileTreeResponse>;
+
+/**
+ * Get combined VFS for multiple packages (Promise API).
+ */
+export declare const getVFS: (packages: readonly PackageSpec[], options?: {
+    readonly autoFetch?: boolean;
+    readonly ttl?: number;
+} | undefined) => Promise<VirtualFileSystem>;
+
+/**
+ * Check if a package is cached (Promise API).
+ */
+export declare const hasCached: (pkg: PackageSpec) => Promise<boolean>;
+
+/**
+ * Raised when an HTTP request to the jsDelivr CDN fails.
+ *
+ * @remarks
+ * The `url` field contains the request URL, `status` is the HTTP status code
+ * (when available), and `message` describes the failure. Network errors may be
+ * transient (e.g. DNS resolution, connection reset) or permanent (e.g. 403
+ * Forbidden). Use `Effect.catchTag` with the `"NetworkError"` tag to handle
+ * this error selectively.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import type { NetworkError } from "type-registry-effect";
+ * import { TypeRegistry, PackageSpec } from "type-registry-effect";
+ * import { NodeLayer } from "type-registry-effect/node";
+ *
+ * const program = TypeRegistry.fetchAndCache(
+ *   new PackageSpec({ name: "zod", version: "3.23.8" }),
+ * ).pipe(
+ *   Effect.catchTag("NetworkError", (err: NetworkError) =>
+ *     Effect.logError(`Request to ${err.url} failed (${err.status ?? "no status"}): ${err.message}`),
+ *   ),
+ * );
+ *
+ * await Effect.runPromise(Effect.provide(program, NodeLayer));
+ * ```
+ *
+ * @see {@link PackageFetcher}
+ * @public
+ */
+export declare class NetworkError extends NetworkErrorBase<{
+    readonly url: string;
+    readonly status?: number;
+    readonly message: string;
+}> {
+}
+
+/**
+ * @internal
+ * Exported for declaration bundling (api-extractor). When `export *` re-exports
+ * a class whose `extends` expression is an inline call like
+ * `Data.TaggedError(...)`, TypeScript emits an un-nameable `_base` symbol in
+ * the declaration file. Splitting the base into a named export gives the
+ * bundler a stable reference.
+ *
+ * @privateRemarks
+ * This base constant must remain a named export so that api-extractor can
+ * resolve the extends clause of {@link NetworkError} to a stable
+ * declaration. Without it the bundled `.d.ts` would contain an anonymous
+ * `_base` symbol that cannot be referenced by downstream consumers.
+ */
+export declare const NetworkErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
+    readonly _tag: "NetworkError";
+} & Readonly<A>;
+
+/**
+ * Node.js platform layer that provides FileSystem and HttpClient,
+ * composed with all TypeRegistry service layers.
+ */
+export declare const NodeLayer: Layer.Layer<CacheService | PackageFetcher | TypeResolver, never, never>;
+
+/**
+ * Effect service interface for fetching type definitions and package metadata
+ * from the jsDelivr CDN.
+ *
+ * @remarks
+ * All network calls are retried up to 3 times with exponential back-off
+ * (starting at 100 ms) and are subject to a 30-second timeout. The live
+ * implementation is provided by {@link PackageFetcherLive}.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import { PackageFetcher } from "type-registry-effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const fetcher = yield* PackageFetcher;
+ *   const meta = yield* fetcher.getVersions("lodash");
+ *   console.log("latest:", meta.tags["latest"]);
+ * });
+ * ```
+ *
+ * @see {@link PackageFetcherLive}
+ *
+ * @public
+ */
+export declare interface PackageFetcher {
+    /** Fetch all published versions and dist-tags for a package. */
+    readonly getVersions: (name: string) => Effect.Effect<PackageMetadata, NetworkError | ParseError>;
+    /** Resolve a semver range or dist-tag to a concrete version string. */
+    readonly resolveVersion: (name: string, ref: string) => Effect.Effect<string, NetworkError | PackageNotFoundError>;
+    /** Retrieve the flat file tree listing for a specific package version. */
+    readonly getFileTree: (pkg: PackageSpec) => Effect.Effect<FileTreeResponse, NetworkError | ParseError>;
+    /** Download a single file from the CDN by path. */
+    readonly downloadFile: (pkg: PackageSpec, path: string) => Effect.Effect<string, NetworkError>;
+    /** Download and schema-validate the `package.json` for a package version. */
+    readonly getPackageJson: (pkg: PackageSpec) => Effect.Effect<PackageJson, NetworkError | ParseError>;
+    /** Download all TypeScript declaration files for a package version, returned as a path-to-content map. */
+    readonly getTypeFiles: (pkg: PackageSpec) => Effect.Effect<Map<string, string>, NetworkError | ParseError>;
+}
+
+/**
+ * Effect Context tag for the {@link PackageFetcher} service.
+ *
+ * @see {@link PackageFetcherLive}
+ */
+export declare const PackageFetcher: Context.Tag<PackageFetcher, PackageFetcher>;
+
+/**
+ * Schema for a validated subset of npm `package.json` fields relevant to type resolution.
+ *
+ * @remarks
+ * This schema captures only the fields the type resolver needs to locate
+ * declaration files within a published package:
+ *
+ * - **`name`** and **`version`** -- identity fields (always required).
+ * - **`types`** / **`typings`** -- legacy top-level type entry points.
+ * - **`main`** / **`module`** -- JavaScript entry points used as fallbacks
+ *   when no explicit type entry is declared.
+ * - **`exports`** -- the modern Node.js conditional exports map; may be a
+ *   simple string or a nested record of conditions.
+ * - **`typesVersions`** -- TypeScript path-mapping overrides keyed by TS
+ *   version ranges (e.g. `">=4.0"`).
+ * - **`dependencies`** / **`peerDependencies`** / **`devDependencies`** --
+ *   used to discover transitive type packages (e.g. `@types/*`).
+ *
+ * Fields outside this set are intentionally ignored to keep validation fast
+ * and the attack surface small.
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { PackageJson } from "type-registry-effect";
+ *
+ * const decode = Schema.decodeUnknownSync(PackageJson);
+ * const pkg = decode({
+ *   name: "zod",
+ *   version: "3.23.8",
+ *   types: "./lib/types.d.ts",
+ *   main: "./lib/index.js",
+ *   exports: {
+ *     ".": { types: "./lib/types.d.ts", import: "./lib/index.mjs" },
+ *   },
+ * });
+ * ```
+ *
+ * @see {@link TypeResolver}
+ * @public
+ */
+export declare const PackageJson: Schema.Struct<{
+    name: typeof Schema.String;
+    version: typeof Schema.String;
+    types: Schema.optional<typeof Schema.String>;
+    typings: Schema.optional<typeof Schema.String>;
+    main: Schema.optional<typeof Schema.String>;
+    module: Schema.optional<typeof Schema.String>;
+    exports: Schema.optional<Schema.Union<[typeof Schema.String, Schema.Record$<typeof Schema.String, typeof Schema.Unknown>]>>;
+    typesVersions: Schema.optional<Schema.Record$<typeof Schema.String, Schema.Record$<typeof Schema.String, Schema.Array$<typeof Schema.String>>>>;
+    dependencies: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.String>>;
+    peerDependencies: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.String>>;
+    devDependencies: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.String>>;
+}>;
+
+export declare type PackageJson = Schema.Schema.Type<typeof PackageJson>;
+
+/**
+ * Version and tag metadata for an npm package as returned by the jsDelivr API.
+ *
+ * @remarks
+ * The `versions` array contains every published version string. The `tags`
+ * record maps dist-tags (e.g. `"latest"`, `"next"`) to their corresponding
+ * version strings.
+ *
+ * @public
+ */
+export declare interface PackageMetadata {
+    readonly versions: string[];
+    readonly tags: Record<string, string>;
+}
+
+/**
+ * Raised when a package or version does not exist on the CDN.
+ *
+ * @remarks
+ * The `name` and `version` fields identify the package that could not be
+ * found, and `message` provides additional context. This typically occurs
+ * when a typo is present in the package name or the requested version has
+ * not been published. Use `Effect.catchTag` with the
+ * `"PackageNotFoundError"` tag to handle this error selectively.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import type { PackageNotFoundError } from "type-registry-effect";
+ * import { TypeRegistry, PackageSpec } from "type-registry-effect";
+ * import { NodeLayer } from "type-registry-effect/node";
+ *
+ * const program = TypeRegistry.fetchAndCache(
+ *   new PackageSpec({ name: "nonexistent-pkg", version: "0.0.0" }),
+ * ).pipe(
+ *   Effect.catchTag("PackageNotFoundError", (err: PackageNotFoundError) =>
+ *     Effect.logWarning(`Package ${err.name}@${err.version} not found: ${err.message}`),
+ *   ),
+ * );
+ *
+ * await Effect.runPromise(Effect.provide(program, NodeLayer));
+ * ```
+ *
+ * @see {@link PackageFetcher.resolveVersion}
+ * @public
+ */
+export declare class PackageNotFoundError extends PackageNotFoundErrorBase<{
+    readonly name: string;
+    readonly version: string;
+    readonly message: string;
+}> {
+}
+
+/**
+ * @internal
+ * Exported for declaration bundling (api-extractor). When `export *` re-exports
+ * a class whose `extends` expression is an inline call like
+ * `Data.TaggedError(...)`, TypeScript emits an un-nameable `_base` symbol in
+ * the declaration file. Splitting the base into a named export gives the
+ * bundler a stable reference.
+ *
+ * @privateRemarks
+ * This base constant must remain a named export so that api-extractor can
+ * resolve the extends clause of {@link PackageNotFoundError} to a stable
+ * declaration. Without it the bundled `.d.ts` would contain an anonymous
+ * `_base` symbol that cannot be referenced by downstream consumers.
+ */
+export declare const PackageNotFoundErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
+    readonly _tag: "PackageNotFoundError";
+} & Readonly<A>;
+
+/**
+ * Immutable value object identifying a package at a specific version.
+ *
+ * @remarks
+ * `PackageSpec` uses {@link https://effect.website/docs/data-types/data/#taggedclass | Data.TaggedClass}
+ * to provide structural equality out of the box. Two `PackageSpec` instances
+ * with the same `name` and `version` are considered equal via `Equal.equals`.
+ * The optional `registry` field allows targeting alternative registries.
+ *
+ * @example
+ * ```typescript
+ * import { Equal } from "effect";
+ * import type { PackageSpec } from "type-registry-effect";
+ * import { PackageSpec as PackageSpecClass } from "type-registry-effect";
+ *
+ * const pkg = new PackageSpecClass({ name: "zod", version: "3.23.8" });
+ * const same = new PackageSpecClass({ name: "zod", version: "3.23.8" });
+ *
+ * // Structural equality via Data.TaggedClass
+ * console.assert(Equal.equals(pkg, same) === true);
+ *
+ * // String representation: "zod@3.23.8"
+ * console.assert(pkg.toString() === "zod@3.23.8");
+ *
+ * // Optional registry for alternative sources
+ * const custom = new PackageSpecClass({
+ *   name: "@myorg/types",
+ *   version: "1.0.0",
+ *   registry: "https://npm.pkg.github.com",
+ * });
+ * ```
+ *
+ * @see {@link CacheService}
+ * @see {@link TypeRegistry}
+ * @public
+ */
+export declare class PackageSpec extends PackageSpecBase<{
+    readonly name: string;
+    readonly version: string;
+    readonly registry?: string;
+}> {
+    toString(): string;
+}
+
+/**
+ * @internal
+ * Exported for declaration bundling (api-extractor). When `export *` re-exports
+ * a class whose `extends` expression is an inline call like
+ * `Data.TaggedClass(...)`, TypeScript emits an un-nameable `_base` symbol in
+ * the declaration file. Splitting the base into a named export gives the
+ * bundler a stable reference.
+ *
+ * @privateRemarks
+ * This base constant must remain a named export so that api-extractor can
+ * resolve the extends clause of {@link PackageSpec} to a stable
+ * declaration. Without it the bundled `.d.ts` would contain an anonymous
+ * `_base` symbol that cannot be referenced by downstream consumers.
+ */
+export declare const PackageSpecBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => Readonly<A> & {
+    readonly _tag: "PackageSpec";
+};
+
+/**
+ * Raised when a CDN response fails schema validation or JSON parsing.
+ *
+ * @remarks
+ * The `source` field identifies what was being parsed (e.g. `"package.json"`,
+ * `"file-tree"`) and `message` describes the validation failure. This
+ * typically indicates the CDN returned an unexpected response shape or
+ * corrupted data. Use `Effect.catchTag` with the `"ParseError"` tag to
+ * handle this error selectively.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import type { ParseError } from "type-registry-effect";
+ * import { TypeRegistry, PackageSpec } from "type-registry-effect";
+ * import { NodeLayer } from "type-registry-effect/node";
+ *
+ * const program = TypeRegistry.fetchAndCache(
+ *   new PackageSpec({ name: "zod", version: "3.23.8" }),
+ * ).pipe(
+ *   Effect.catchTag("ParseError", (err: ParseError) =>
+ *     Effect.logError(`Failed to parse ${err.source}: ${err.message}`),
+ *   ),
+ * );
+ *
+ * await Effect.runPromise(Effect.provide(program, NodeLayer));
+ * ```
+ *
+ * @see {@link PackageFetcher.getPackageJson}
+ * @public
+ */
+export declare class ParseError extends ParseErrorBase<{
+    readonly source: string;
+    readonly message: string;
+}> {
+}
+
+/**
+ * @internal
+ * Exported for declaration bundling (api-extractor). When `export *` re-exports
+ * a class whose `extends` expression is an inline call like
+ * `Data.TaggedError(...)`, TypeScript emits an un-nameable `_base` symbol in
+ * the declaration file. Splitting the base into a named export gives the
+ * bundler a stable reference.
+ *
+ * @privateRemarks
+ * This base constant must remain a named export so that api-extractor can
+ * resolve the extends clause of {@link ParseError} to a stable
+ * declaration. Without it the bundled `.d.ts` would contain an anonymous
+ * `_base` symbol that cannot be referenced by downstream consumers.
+ */
+export declare const ParseErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
+    readonly _tag: "ParseError";
+} & Readonly<A>;
+
+/**
+ * Raised when an import specifier cannot be resolved to a module within a package.
+ *
+ * @remarks
+ * The `package` field is the package name, `specifier` is the import path
+ * that could not be resolved, and `message` describes the failure cause.
+ * This occurs when the package's exports map, `typesVersions`, or file tree
+ * do not contain a matching entry for the requested specifier. Use
+ * `Effect.catchTag` with the `"ResolutionError"` tag to handle this error
+ * selectively.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import type { ResolutionError } from "type-registry-effect";
+ * import { TypeResolver, PackageSpec } from "type-registry-effect";
+ * import { NodeLayer } from "type-registry-effect/node";
+ *
+ * const program = TypeResolver.resolveImport(
+ *   new PackageSpec({ name: "zod", version: "3.23.8" }),
+ *   "./nonexistent",
+ * ).pipe(
+ *   Effect.catchTag("ResolutionError", (err: ResolutionError) =>
+ *     Effect.logWarning(`Cannot resolve "${err.specifier}" in ${err.package}: ${err.message}`),
+ *   ),
+ * );
+ *
+ * await Effect.runPromise(Effect.provide(program, NodeLayer));
+ * ```
+ *
+ * @see {@link TypeResolver.resolveImport}
+ * @public
+ */
+export declare class ResolutionError extends ResolutionErrorBase<{
+    readonly package: string;
+    readonly specifier: string;
+    readonly message: string;
+}> {
+}
+
+/**
+ * @internal
+ * Exported for declaration bundling (api-extractor). When `export *` re-exports
+ * a class whose `extends` expression is an inline call like
+ * `Data.TaggedError(...)`, TypeScript emits an un-nameable `_base` symbol in
+ * the declaration file. Splitting the base into a named export gives the
+ * bundler a stable reference.
+ *
+ * @privateRemarks
+ * This base constant must remain a named export so that api-extractor can
+ * resolve the extends clause of {@link ResolutionError} to a stable
+ * declaration. Without it the bundled `.d.ts` would contain an anonymous
+ * `_base` symbol that cannot be referenced by downstream consumers.
+ */
+export declare const ResolutionErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
+    readonly _tag: "ResolutionError";
+} & Readonly<A>;
+
+/**
+ * Represents a resolved module path within a package.
+ *
+ * @remarks
+ * After the {@link TypeResolver} walks a package's exports and file tree, each
+ * resolvable import specifier maps to a `ResolvedModule`. The `filePath` is
+ * relative to the package root, and `isTypeDefinition` indicates whether the
+ * file is a `.d.ts` (or `.d.mts` / `.d.cts`) declaration file. The `package`
+ * field links back to the originating {@link PackageSpec}.
+ *
+ * @example
+ * ```typescript
+ * import type { ResolvedModule, PackageSpec } from "type-registry-effect";
+ * import {
+ *   ResolvedModule as ResolvedModuleClass,
+ *   PackageSpec as PackageSpecClass,
+ * } from "type-registry-effect";
+ *
+ * const mod = new ResolvedModuleClass({
+ *   filePath: "dist/index.d.ts",
+ *   isTypeDefinition: true,
+ *   package: new PackageSpecClass({ name: "zod", version: "3.23.8" }),
+ * });
+ * ```
+ *
+ * @see {@link TypeResolver.resolveImport}
+ * @see {@link TypeResolver.resolveTypeEntries}
+ * @public
+ */
+export declare class ResolvedModule extends ResolvedModuleBase<{
+    readonly filePath: string;
+    readonly isTypeDefinition: boolean;
+    readonly package: PackageSpec;
+}> {
+}
+
+/**
+ * @internal
+ * Exported for declaration bundling (api-extractor). When `export *` re-exports
+ * a class whose `extends` expression is an inline call like
+ * `Data.TaggedClass(...)`, TypeScript emits an un-nameable `_base` symbol in
+ * the declaration file. Splitting the base into a named export gives the
+ * bundler a stable reference.
+ *
+ * @privateRemarks
+ * This base constant must remain a named export so that api-extractor can
+ * resolve the extends clause of {@link ResolvedModule} to a stable
+ * declaration. Without it the bundled `.d.ts` would contain an anonymous
+ * `_base` symbol that cannot be referenced by downstream consumers.
+ */
+export declare const ResolvedModuleBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => Readonly<A> & {
+    readonly _tag: "ResolvedModule";
+};
+
+/**
+ * Resolve a version reference to a specific version (Promise API).
+ */
+export declare const resolveVersion: (name: string, ref: string) => Promise<string>;
+
+/**
+ * Raised when an operation exceeds its configured time limit.
+ *
+ * @remarks
+ * The `operation` field describes what was being performed (e.g.
+ * `"fetchFileTree"`, `"resolveVersion"`), `duration` is the elapsed time in
+ * milliseconds, and `message` provides additional context. Use
+ * `Effect.catchTag` with the `"TimeoutError"` tag to handle this error
+ * selectively.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import type { TimeoutError } from "type-registry-effect";
+ * import { TypeRegistry, PackageSpec } from "type-registry-effect";
+ * import { NodeLayer } from "type-registry-effect/node";
+ *
+ * const program = TypeRegistry.fetchAndCache(
+ *   new PackageSpec({ name: "zod", version: "3.23.8" }),
+ * ).pipe(
+ *   Effect.catchTag("TimeoutError", (err: TimeoutError) =>
+ *     Effect.logWarning(`${err.operation} timed out after ${err.duration}ms: ${err.message}`),
+ *   ),
+ * );
+ *
+ * await Effect.runPromise(Effect.provide(program, NodeLayer));
+ * ```
+ *
+ * @public
+ */
+export declare class TimeoutError extends TimeoutErrorBase<{
+    readonly operation: string;
+    readonly duration: number;
+    readonly message: string;
+}> {
+}
+
+/**
+ * @internal
+ * Exported for declaration bundling (api-extractor). When `export *` re-exports
+ * a class whose `extends` expression is an inline call like
+ * `Data.TaggedError(...)`, TypeScript emits an un-nameable `_base` symbol in
+ * the declaration file. Splitting the base into a named export gives the
+ * bundler a stable reference.
+ *
+ * @privateRemarks
+ * This base constant must remain a named export so that api-extractor can
+ * resolve the extends clause of {@link TimeoutError} to a stable
+ * declaration. Without it the bundled `.d.ts` would contain an anonymous
+ * `_base` symbol that cannot be referenced by downstream consumers.
+ */
+export declare const TimeoutErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
+    readonly _tag: "TimeoutError";
+} & Readonly<A>;
+
+/**
+ * Effect service interface for import resolution using `package.json` metadata.
+ *
+ * @remarks
+ * Resolution is attempted in the following order:
+ *
+ * 1. **`exports`** -- the `"types"` condition inside the package's exports map.
+ * 2. **`typesVersions`** -- the `"*"` entry of `typesVersions` with wildcard
+ *    matching.
+ * 3. **`types` / `typings`** -- top-level fields pointing at the main
+ *    declaration file.
+ * 4. **Conventional** -- extension swapping (`.js` to `.d.ts`) and
+ *    `index.d.ts` fallback.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import { TypeResolver } from "type-registry-effect";
+ * import type { PackageJson } from "type-registry-effect";
+ * import type { PackageSpec } from "type-registry-effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const resolver = yield* TypeResolver;
+ *   const resolved = yield* resolver.resolveMainEntry(
+ *     { name: "lodash", version: "4.17.21" } as unknown as PackageJson,
+ *     { name: "lodash", version: "4.17.21" } as PackageSpec,
+ *   );
+ *   console.log("main types:", resolved.filePath);
+ * });
+ * ```
+ *
+ * @see {@link TypeResolverLive}
+ *
+ * @public
+ */
+export declare interface TypeResolver {
+    /**
+     * Resolve a bare or deep-import specifier to a type definition path within
+     * the package.
+     */
+    readonly resolveImport: (specifier: string, packageJson: PackageJson, pkg: PackageSpec) => Effect.Effect<ResolvedModule, ResolutionError>;
+    /**
+     * Resolve the main (root `"."`) type entry point for a package.
+     */
+    readonly resolveMainEntry: (packageJson: PackageJson, pkg: PackageSpec) => Effect.Effect<ResolvedModule, ResolutionError>;
+    /**
+     * Collect all type entry points declared by the package, including the main
+     * entry and any additional sub-path exports that expose types.
+     */
+    readonly resolveTypeEntries: (packageJson: PackageJson, pkg: PackageSpec) => Effect.Effect<ReadonlyArray<ResolvedModule>, ResolutionError>;
+    /**
+     * Given a JavaScript file path, derive the corresponding `.d.ts` / `.d.mts`
+     * / `.d.cts` path. Returns `null` when no type definition can be inferred.
+     */
+    readonly findTypeDefinition: (jsFilePath: string, packageJson: PackageJson, pkg: PackageSpec) => Effect.Effect<ResolvedModule | null, ResolutionError>;
+}
+
+/**
+ * Effect Context tag for the {@link TypeResolver} service.
+ *
+ * @see {@link TypeResolverLive}
+ */
+export declare const TypeResolver: Context.Tag<TypeResolver, TypeResolver>;
+
+/**
+ * A `Map<string, string>` that maps virtual file paths to their contents.
+ *
+ * @remarks
+ * Keys are prefixed with `node_modules/` so the map can be fed directly into
+ * an in-memory TypeScript compiler host. Values are the UTF-8 file contents
+ * (typically `.d.ts` declarations).
+ *
+ * @example
+ * ```typescript
+ * import type { VirtualFileSystem } from "type-registry-effect";
+ *
+ * const vfs: VirtualFileSystem = new Map([
+ *   ["node_modules/lodash/index.d.ts", "declare module 'lodash' { ... }"],
+ * ]);
+ * ```
+ *
+ * @see {@link CacheService}
+ *
+ * @public
+ */
+export declare type VirtualFileSystem = Map<string, string>;
+
+export { VirtualTypeScriptEnvironment }
+
+export { }