type-registry-effect 0.1.0

package/index.d.ts

@@ -0,0 +1,1754 @@
+/**
+ * type-registry-effect — platform-agnostic entry point.
+ *
+ * Provides composable Effect programs for fetching, caching, and resolving
+ * TypeScript type definitions from npm packages via the jsDelivr CDN.
+ *
+ * @remarks
+ * This entry point contains only platform-agnostic code. It exports:
+ *
+ * - **Namespace modules** — {@link TypeRegistry} (composable programs) and
+ *   {@link VirtualPackage} (synthetic packages from local declarations).
+ * - **Schemas** — {@link PackageSpec}, {@link CacheMetadata},
+ *   {@link ResolvedModule}, {@link PackageJson}, {@link FileTreeResponse}.
+ * - **Errors** — {@link CacheError}, {@link NetworkError},
+ *   {@link PackageNotFoundError}, {@link ParseError},
+ *   {@link ResolutionError}, {@link TimeoutError}.
+ * - **Services** — {@link CacheService}, {@link PackageFetcher},
+ *   {@link TypeResolver}.
+ * - **Layers** — {@link CacheServiceLive}, {@link PackageFetcherLive},
+ *   {@link TypeResolverLive}, {@link TypeRegistryLive}.
+ * - **Events** — {@link LogEventSchema}, {@link LogEvent}.
+ *
+ * For a Node.js convenience layer and Promise-returning wrappers, import
+ * from `type-registry-effect/node` instead.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import { TypeRegistry, PackageSpec, TypeRegistryLive } from "type-registry-effect";
+ * import { NodeFileSystem, NodeHttpClient } from "@effect/platform-node";
+ *
+ * const program = Effect.gen(function* () {
+ *   const pkg = new PackageSpec({ name: "zod", version: "3.23.8" });
+ *   yield* TypeRegistry.fetchAndCache(pkg);
+ *   return yield* TypeRegistry.getVFS([pkg]);
+ * });
+ *
+ * const vfs = await program.pipe(
+ *   Effect.provide(TypeRegistryLive),
+ *   Effect.provide(NodeFileSystem.layer),
+ *   Effect.provide(NodeHttpClient.layerUndici),
+ *   Effect.runPromise,
+ * );
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import { Context } from 'effect';
+import { Effect } from 'effect';
+import { Equals } from 'effect/Types';
+import { FileSystem } from '@effect/platform';
+import { HttpClient } from '@effect/platform';
+import { Layer } from 'effect';
+import { Schema } from 'effect';
+import * as Schema_2 from 'effect/Schema';
+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>;
+
+/**
+ * Default {@link CacheService} layer using the XDG cache directory.
+ *
+ * @remarks
+ * This is equivalent to calling {@link makeNodeCacheLayer} with no arguments.
+ * Requires a {@link @effect/platform#FileSystem | FileSystem} layer to be
+ * provided at composition time.
+ *
+ * @see {@link makeNodeCacheLayer}
+ *
+ * @public
+ */
+export declare const CacheServiceLive: Layer.Layer<CacheService, never, FileSystem.FileSystem>;
+
+/**
+ * Remove a package and all of its cached files from the disk cache.
+ *
+ * @param pkg - The package specification to remove.
+ * @returns An Effect that succeeds with `void` once the cache entry is deleted.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import { TypeRegistry, PackageSpec } from "type-registry-effect";
+ * import { NodeLayer } from "type-registry-effect/node";
+ *
+ * const program = Effect.gen(function* () {
+ *   const pkg = new PackageSpec({ name: "zod", version: "3.23.8" });
+ *   yield* TypeRegistry.clearCache(pkg);
+ *   console.log("Cache cleared for zod@3.23.8");
+ * });
+ *
+ * await Effect.runPromise(Effect.provide(program, NodeLayer));
+ * ```
+ *
+ * @see {@link hasCached} to check existence before clearing
+ * @see {@link fetchAndCache} to repopulate the cache afterward
+ *
+ * @public
+ */
+declare const clearCache: (pkg: PackageSpec) => Effect.Effect<void, CacheError, CacheService>;
+
+/**
+ * Create a validated {@link LogEvent} from unknown data.
+ *
+ * @remarks
+ * Decodes `event` synchronously through {@link LogEventSchema}. Throws a
+ * parse error if the input does not conform to any variant of the schema.
+ * This is intended for internal use within the library's logging
+ * infrastructure.
+ *
+ * @param event - Raw, unvalidated event data.
+ * @returns A fully validated {@link LogEvent}.
+ * @throws `ParseError` when `event` does not match {@link LogEventSchema}.
+ *
+ * @internal
+ */
+export declare function createLogEvent(event: unknown): LogEvent;
+
+/**
+ * Fetch type definitions for a package from the jsDelivr CDN and write them
+ * to the disk cache.
+ *
+ * @remarks
+ * The function downloads the `package.json` and every `.d.ts` file published
+ * by the package, then persists them under the {@link CacheService} storage
+ * directory. A {@link CacheMetadata} record is written alongside the files so
+ * that future cache hits can evaluate freshness.
+ *
+ * The optional `ttl` (time-to-live) is stored in the metadata and expressed
+ * in **milliseconds**. When a subsequent read finds that the cache entry is
+ * older than `ttl`, the entry is considered stale and a re-fetch is triggered
+ * by higher-level operations such as {@link getPackageVFS}.
+ *
+ * @param pkg - The package specification to fetch.
+ * @param options - Optional configuration. When provided, `options.ttl` sets
+ *   the time-to-live in milliseconds for the cached entry.
+ * @returns An Effect that succeeds with `void` once all files are written.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import { TypeRegistry, PackageSpec } from "type-registry-effect";
+ * import { NodeLayer } from "type-registry-effect/node";
+ *
+ * const program = Effect.gen(function* () {
+ *   const pkg = new PackageSpec({ name: "lodash", version: "4.17.21" });
+ *   // Cache with a 1-hour TTL
+ *   yield* TypeRegistry.fetchAndCache(pkg, { ttl: 60 * 60 * 1000 });
+ * });
+ *
+ * await Effect.runPromise(Effect.provide(program, NodeLayer));
+ * ```
+ *
+ * @see {@link hasCached} to check before fetching
+ * @see {@link getPackageVFS} for a higher-level API that auto-fetches
+ *
+ * @public
+ */
+declare const fetchAndCache: (pkg: PackageSpec, options?: {
+    readonly ttl?: number;
+} | undefined) => Effect.Effect<void, CacheError | NetworkError | ParseError, CacheService | PackageFetcher>;
+
+/**
+ * Schema for a single file entry in the jsDelivr flat file tree response.
+ *
+ * @remarks
+ * Each entry contains the file `name` (path relative to the package root),
+ * a content `hash` for integrity checking, a `time` timestamp string, and
+ * the file `size` in bytes. This schema is used to validate raw JSON from
+ * the jsDelivr data API before further processing.
+ *
+ * @example
+ * ```typescript
+ * import { Schema } from "effect";
+ * import { FileTreeEntry } from "type-registry-effect";
+ *
+ * const decode = Schema.decodeUnknownSync(FileTreeEntry);
+ * const entry = decode({
+ *   name: "/dist/index.d.ts",
+ *   hash: "abc123",
+ *   time: "2024-01-15T10:30:00.000Z",
+ *   size: 4096,
+ * });
+ * ```
+ *
+ * @see {@link PackageFetcher.getFileTree}
+ * @public
+ */
+export declare const FileTreeEntry: Schema.Struct<{
+    name: typeof Schema.String;
+    hash: typeof Schema.String;
+    time: typeof Schema.String;
+    size: typeof Schema.Number;
+}>;
+
+export declare type FileTreeEntry = Schema.Schema.Type<typeof FileTreeEntry>;
+
+/**
+ * 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>;
+
+/**
+ * Return the default cache directory used by `effect-type-registry`.
+ *
+ * @remarks
+ * Resolves to `<XDG_CACHE_HOME>/effect-type-registry`. This is the path
+ * used by the built-in Node.js cache layer when no custom directory is
+ * provided.
+ *
+ * @returns Absolute path to the default cache directory
+ *   (e.g. `~/.cache/effect-type-registry`).
+ *
+ * @see {@link makeNodeCacheLayer} in `"type-registry-effect/node"` which
+ *   calls this function when constructing the default layer.
+ *
+ * @public
+ */
+export declare function getDefaultCacheDir(): string;
+
+/**
+ * Get a {@link VirtualFileSystem} for a single package, optionally fetching
+ * it from the CDN first if it is not already cached.
+ *
+ * @remarks
+ * When `autoFetch` is `true` (the default) and the package is not present in
+ * the cache, this function transparently calls {@link fetchAndCache} before
+ * building the VFS. Set `autoFetch` to `false` to restrict the operation to
+ * cached data only; a {@link PackageNotFoundError} is raised if the package
+ * is missing.
+ *
+ * The returned VFS maps file paths (relative to `node_modules/<package>`) to
+ * their string contents.
+ *
+ * @param pkg - The package specification to retrieve.
+ * @param options - Optional configuration. When provided, `options.autoFetch`
+ *   controls whether to fetch from the CDN on a cache miss (default `true`),
+ *   and `options.ttl` sets the time-to-live in milliseconds forwarded to
+ *   {@link fetchAndCache}.
+ * @returns An Effect that succeeds with the package's {@link VirtualFileSystem}.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import type { VirtualFileSystem } from "type-registry-effect";
+ * import { TypeRegistry, PackageSpec } from "type-registry-effect";
+ * import { NodeLayer } from "type-registry-effect/node";
+ *
+ * const program = Effect.gen(function* () {
+ *   const pkg = new PackageSpec({ name: "zod", version: "3.23.8" });
+ *   // Auto-fetches if not cached
+ *   const vfs: VirtualFileSystem = yield* TypeRegistry.getPackageVFS(pkg);
+ *   console.log(`Files: ${[...vfs.keys()].join(", ")}`);
+ *   return vfs;
+ * });
+ *
+ * const vfs = await Effect.runPromise(Effect.provide(program, NodeLayer));
+ * ```
+ *
+ * @see {@link getVFS} to load multiple packages at once
+ * @see {@link fetchAndCache} for the underlying fetch + write logic
+ *
+ * @public
+ */
+declare const getPackageVFS: (pkg: PackageSpec, options?: {
+    readonly autoFetch?: boolean;
+    readonly ttl?: number;
+} | undefined) => Effect.Effect<VirtualFileSystem, CacheError | NetworkError | PackageNotFoundError | ParseError, CacheService | PackageFetcher>;
+
+/**
+ * Get all type entry points exported by a cached package.
+ *
+ * @remarks
+ * Reads the cached `package.json` and delegates to {@link TypeResolver} to
+ * enumerate every entry point that exposes type definitions (via `exports`,
+ * `types`, or `typings` fields). The package must already be in the cache.
+ *
+ * @param pkg - The cached package to inspect.
+ * @returns An Effect that succeeds with a read-only array of {@link ResolvedModule} entries.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import type { ResolvedModule } from "type-registry-effect";
+ * import { TypeRegistry, PackageSpec } from "type-registry-effect";
+ * import { NodeLayer } from "type-registry-effect/node";
+ *
+ * const program = Effect.gen(function* () {
+ *   const pkg = new PackageSpec({ name: "effect", version: "3.12.5" });
+ *   yield* TypeRegistry.fetchAndCache(pkg);
+ *   const entries: ReadonlyArray<ResolvedModule> = yield* TypeRegistry.getTypeEntries(pkg);
+ *   for (const entry of entries) {
+ *     console.log(`${entry.specifier} -> ${entry.resolvedPath}`);
+ *   }
+ *   return entries;
+ * });
+ *
+ * const entries = await Effect.runPromise(Effect.provide(program, NodeLayer));
+ * ```
+ *
+ * @see {@link resolveImport} to resolve a single specifier
+ * @see {@link TypeResolver} for the underlying resolution service
+ *
+ * @public
+ */
+declare const getTypeEntries: (pkg: PackageSpec) => Effect.Effect<readonly ResolvedModule[], CacheError | ParseError | ResolutionError, CacheService | TypeResolver>;
+
+/**
+ * Get a combined {@link VirtualFileSystem} for multiple packages with
+ * graceful degradation on per-package failures.
+ *
+ * @remarks
+ * Packages are fetched concurrently with a concurrency limit of **5**.
+ * Individual package failures are caught and accumulated rather than
+ * aborting the entire batch. The operation only fails with a
+ * {@link PackageNotFoundError} when **every** requested package fails.
+ * When at least one package succeeds, the merged VFS is returned and
+ * failing packages are silently skipped.
+ *
+ * This partial-failure strategy makes the function suitable for
+ * best-effort scenarios such as editor integrations where missing type
+ * definitions for one dependency should not block the rest.
+ *
+ * @param packages - Array of package specifications to load.
+ * @param options - Optional configuration forwarded to {@link getPackageVFS}.
+ *   When provided, `options.autoFetch` controls whether to fetch missing
+ *   packages from the CDN (default `true`), and `options.ttl` sets the
+ *   time-to-live in milliseconds for newly cached entries.
+ * @returns An Effect that succeeds with the merged {@link VirtualFileSystem}.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import type { VirtualFileSystem } from "type-registry-effect";
+ * import { TypeRegistry, PackageSpec } from "type-registry-effect";
+ * import { NodeLayer } from "type-registry-effect/node";
+ *
+ * const program = Effect.gen(function* () {
+ *   const packages = [
+ *     new PackageSpec({ name: "zod", version: "3.23.8" }),
+ *     new PackageSpec({ name: "effect", version: "3.12.5" }),
+ *   ];
+ *   const vfs: VirtualFileSystem = yield* TypeRegistry.getVFS(packages);
+ *   console.log(`Total VFS entries: ${vfs.size}`);
+ *   return vfs;
+ * });
+ *
+ * const vfs = await Effect.runPromise(Effect.provide(program, NodeLayer));
+ * ```
+ *
+ * @see {@link getPackageVFS} for loading a single package
+ *
+ * @public
+ */
+declare const getVFS: (packages: readonly PackageSpec[], options?: {
+    readonly autoFetch?: boolean;
+    readonly ttl?: number;
+} | undefined) => Effect.Effect<VirtualFileSystem, PackageNotFoundError, CacheService | PackageFetcher>;
+
+/**
+ * Check whether a package already exists in the disk cache.
+ *
+ * @remarks
+ * This performs a lightweight existence check against {@link CacheService} without
+ * reading any file contents. Use it to decide whether to fetch before calling
+ * {@link fetchAndCache}.
+ *
+ * @param pkg - The package specification to look up.
+ * @returns An Effect that succeeds with `true` when the package is cached, `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import { TypeRegistry, PackageSpec } from "type-registry-effect";
+ * import { NodeLayer } from "type-registry-effect/node";
+ *
+ * const program = Effect.gen(function* () {
+ *   const pkg = new PackageSpec({ name: "zod", version: "3.23.8" });
+ *   const exists = yield* TypeRegistry.hasCached(pkg);
+ *   console.log(`zod@3.23.8 cached: ${exists}`);
+ *   return exists;
+ * });
+ *
+ * const result = await Effect.runPromise(Effect.provide(program, NodeLayer));
+ * ```
+ *
+ * @public
+ */
+declare const hasCached: (pkg: PackageSpec) => Effect.Effect<boolean, CacheError, CacheService>;
+
+/**
+ * Type-safe log event inferred from {@link LogEventSchema}.
+ *
+ * @remarks
+ * This is a discriminated union — narrow it using the `event` string literal
+ * field. Each variant carries a strongly-typed `data` payload.
+ *
+ * @example
+ * ```typescript
+ * import type { LogEvent } from "type-registry-effect";
+ *
+ * function handleEvent(event: LogEvent): void {
+ *   switch (event.event) {
+ *     case "cache.hit":
+ *       console.log(`Cache hit for ${event.data.package}@${event.data.version}`);
+ *       break;
+ *     case "cache.miss":
+ *       console.log(`Cache miss for ${event.data.package}@${event.data.version}`);
+ *       break;
+ *     case "package.loaded":
+ *       console.log(`Loaded ${event.data.files} files from ${event.data.source}`);
+ *       break;
+ *     case "packages.batch.complete":
+ *       console.log(`Batch done: ${event.data.loaded}/${event.data.total} in ${event.data.durationMs}ms`);
+ *       break;
+ *     default:
+ *       console.log(`[${event.level}] ${event.message}`);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link LogEventSchema} for the runtime schema definition
+ *
+ * @public
+ */
+export declare type LogEvent = Schema_2.Schema.Type<typeof LogEventSchema>;
+
+/**
+ * Callback function type for receiving validated {@link LogEvent} instances.
+ *
+ * @remarks
+ * Pass an implementation of this type to logging integrations that subscribe
+ * to TypeRegistry operations. The handler is invoked synchronously with each
+ * event after it has been validated against the {@link LogEventSchema}.
+ *
+ * @see {@link LogEvent} for the event payload type
+ * @see {@link LogEventSchema} for the runtime schema
+ *
+ * @public
+ */
+export declare type LogEventHandler = (event: LogEvent) => void;
+
+/**
+ * Discriminated union schema for all structured log events emitted by
+ * TypeRegistry operations.
+ *
+ * @remarks
+ * The following event types are defined:
+ *
+ * - `"package.version.resolved"` — a version reference was resolved to a pinned version.
+ * - `"cache.hit"` — a package was found in the disk cache and is fresh.
+ * - `"cache.stale"` — a cached package exceeded its TTL.
+ * - `"cache.miss"` — a package was not found in the cache.
+ * - `"package.fetch.start"` — a network fetch has begun for a package.
+ * - `"package.loaded"` — a package was successfully loaded (from cache or network).
+ * - `"package.load.failed"` — loading a package failed.
+ * - `"packages.batch.start"` — a batch operation started for multiple packages.
+ * - `"packages.batch.complete"` — a batch operation finished with summary statistics.
+ * - `"typescript.cache.created"` — a TypeScript in-memory cache was created from VFS data.
+ *
+ * Use the `event` field on the decoded value to narrow the type in a
+ * `switch`/`case` or `if` block.
+ *
+ * @see {@link LogEvent} for the inferred TypeScript type
+ * @see {@link LogEventHandler} for the callback signature
+ *
+ * @example
+ * ```typescript
+ * import type { LogEventHandler } from "type-registry-effect";
+ *
+ * const handler: LogEventHandler = (event) => {
+ *   if (event.event === "package.loaded") {
+ *     console.log(`Loaded ${event.data.package}@${event.data.version}`);
+ *   }
+ * };
+ * ```
+ *
+ * @public
+ */
+export declare const LogEventSchema: Schema_2.Union<[Schema_2.Struct<{
+    event: Schema_2.Literal<["package.version.resolved"]>;
+    level: Schema_2.Literal<["info"]>;
+    message: typeof Schema_2.String;
+    timestamp: typeof Schema_2.Number;
+    fiber: Schema_2.optional<typeof Schema_2.String>;
+    data: Schema_2.Struct<{
+        package: typeof Schema_2.String;
+        requested: typeof Schema_2.String;
+        resolved: typeof Schema_2.String;
+    }>;
+}>, Schema_2.Struct<{
+    event: Schema_2.Literal<["cache.hit"]>;
+    level: Schema_2.Literal<["info"]>;
+    message: typeof Schema_2.String;
+    timestamp: typeof Schema_2.Number;
+    fiber: Schema_2.optional<typeof Schema_2.String>;
+    data: Schema_2.Struct<{
+        package: typeof Schema_2.String;
+        version: typeof Schema_2.String;
+        ageMinutes: typeof Schema_2.Number;
+    }>;
+}>, Schema_2.Struct<{
+    event: Schema_2.Literal<["cache.stale"]>;
+    level: Schema_2.Literal<["debug"]>;
+    message: typeof Schema_2.String;
+    timestamp: typeof Schema_2.Number;
+    fiber: Schema_2.optional<typeof Schema_2.String>;
+    data: Schema_2.Struct<{
+        package: typeof Schema_2.String;
+        version: typeof Schema_2.String;
+        ageMinutes: typeof Schema_2.Number;
+        ttlMinutes: typeof Schema_2.Number;
+    }>;
+}>, Schema_2.Struct<{
+    event: Schema_2.Literal<["cache.miss"]>;
+    level: Schema_2.Literal<["debug"]>;
+    message: typeof Schema_2.String;
+    timestamp: typeof Schema_2.Number;
+    fiber: Schema_2.optional<typeof Schema_2.String>;
+    data: Schema_2.Struct<{
+        package: typeof Schema_2.String;
+        version: typeof Schema_2.String;
+    }>;
+}>, Schema_2.Struct<{
+    event: Schema_2.Literal<["package.fetch.start"]>;
+    level: Schema_2.Literal<["debug"]>;
+    message: typeof Schema_2.String;
+    timestamp: typeof Schema_2.Number;
+    fiber: Schema_2.optional<typeof Schema_2.String>;
+    data: Schema_2.Struct<{
+        package: typeof Schema_2.String;
+        version: typeof Schema_2.String;
+    }>;
+}>, Schema_2.Struct<{
+    event: Schema_2.Literal<["package.loaded"]>;
+    level: Schema_2.Literal<["info"]>;
+    message: typeof Schema_2.String;
+    timestamp: typeof Schema_2.Number;
+    fiber: Schema_2.optional<typeof Schema_2.String>;
+    data: Schema_2.Struct<{
+        package: typeof Schema_2.String;
+        version: typeof Schema_2.String;
+        files: typeof Schema_2.Number;
+        source: Schema_2.Literal<["cache", "network"]>;
+    }>;
+}>, Schema_2.Struct<{
+    event: Schema_2.Literal<["package.load.failed"]>;
+    level: Schema_2.Literal<["warn"]>;
+    message: typeof Schema_2.String;
+    timestamp: typeof Schema_2.Number;
+    fiber: Schema_2.optional<typeof Schema_2.String>;
+    data: Schema_2.Struct<{
+        package: typeof Schema_2.String;
+        version: typeof Schema_2.String;
+        error: typeof Schema_2.String;
+    }>;
+}>, Schema_2.Struct<{
+    event: Schema_2.Literal<["packages.batch.start"]>;
+    level: Schema_2.Literal<["debug"]>;
+    message: typeof Schema_2.String;
+    timestamp: typeof Schema_2.Number;
+    fiber: Schema_2.optional<typeof Schema_2.String>;
+    data: Schema_2.Struct<{
+        total: typeof Schema_2.Number;
+        packages: Schema_2.Array$<typeof Schema_2.String>;
+    }>;
+}>, Schema_2.Struct<{
+    event: Schema_2.Literal<["packages.batch.complete"]>;
+    level: Schema_2.Literal<["info"]>;
+    message: typeof Schema_2.String;
+    timestamp: typeof Schema_2.Number;
+    fiber: Schema_2.optional<typeof Schema_2.String>;
+    data: Schema_2.Struct<{
+        loaded: typeof Schema_2.Number;
+        failed: typeof Schema_2.Number;
+        total: typeof Schema_2.Number;
+        totalFiles: typeof Schema_2.Number;
+        durationMs: typeof Schema_2.Number;
+    }>;
+}>, Schema_2.Struct<{
+    event: Schema_2.Literal<["typescript.cache.created"]>;
+    level: Schema_2.Literal<["info"]>;
+    message: typeof Schema_2.String;
+    timestamp: typeof Schema_2.Number;
+    fiber: Schema_2.optional<typeof Schema_2.String>;
+    data: Schema_2.Struct<{
+        packages: Schema_2.Array$<typeof Schema_2.String>;
+        fileCount: typeof Schema_2.Number;
+        rootFiles: typeof Schema_2.Number;
+    }>;
+}>]>;
+
+/**
+ * Creates a {@link CacheService} layer backed by the local filesystem.
+ *
+ * @param baseDir - Optional custom cache directory. When omitted the XDG
+ *   cache directory is used (see {@link getDefaultCacheDir}).
+ * @returns A `Layer` providing {@link CacheService} that requires
+ *   {@link @effect/platform#FileSystem | FileSystem}.
+ *
+ * @example
+ * ```typescript
+ * import { NodeFileSystem } from "@effect/platform-node";
+ * import { Effect, Layer } from "effect";
+ * import { CacheService, makeNodeCacheLayer } from "type-registry-effect";
+ *
+ * const CustomCache = makeNodeCacheLayer("/tmp/my-type-cache");
+ * const MainLayer = Layer.provide(CustomCache, NodeFileSystem.layer);
+ *
+ * const program = Effect.gen(function* () {
+ *   const cache = yield* CacheService;
+ *   console.log("using custom cache dir");
+ * });
+ *
+ * Effect.runPromise(Effect.provide(program, MainLayer));
+ * ```
+ *
+ * @see {@link CacheService}
+ * @see {@link getDefaultCacheDir}
+ *
+ * @public
+ */
+export declare const makeNodeCacheLayer: (baseDir?: string | undefined) => Layer.Layer<CacheService, never, FileSystem.FileSystem>;
+
+/**
+ * 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>;
+
+/**
+ * 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>;
+
+/**
+ * Live {@link PackageFetcher} layer that fetches package metadata and type
+ * definitions from the jsDelivr CDN.
+ *
+ * @remarks
+ * All HTTP requests are retried up to **3 times** with exponential back-off
+ * (starting at 100 ms) and time out after **30 seconds**. Requires an
+ * {@link @effect/platform#HttpClient | HttpClient} layer to be provided at
+ * composition time.
+ *
+ * @see {@link PackageFetcher}
+ *
+ * @public
+ */
+export declare const PackageFetcherLive: Layer.Layer<PackageFetcher, never, HttpClient.HttpClient>;
+
+/**
+ * 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 an import specifier (e.g. `"zod"`, `"zod/lib/types"`) against a
+ * cached package's `package.json` exports map.
+ *
+ * @remarks
+ * The package must already be present in the cache. The resolution logic
+ * delegates to {@link TypeResolver} which interprets the `exports`, `types`,
+ * and `typings` fields of the cached `package.json`.
+ *
+ * @param pkg - The cached package to resolve against.
+ * @param specifier - The bare import specifier to resolve (e.g. `"zod"` or `"zod/lib/types"`).
+ * @returns An Effect that succeeds with a {@link ResolvedModule} describing the resolved file.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import type { ResolvedModule } from "type-registry-effect";
+ * import { TypeRegistry, PackageSpec } from "type-registry-effect";
+ * import { NodeLayer } from "type-registry-effect/node";
+ *
+ * const program = Effect.gen(function* () {
+ *   const pkg = new PackageSpec({ name: "zod", version: "3.23.8" });
+ *   yield* TypeRegistry.fetchAndCache(pkg);
+ *   const resolved: ResolvedModule = yield* TypeRegistry.resolveImport(pkg, "zod");
+ *   console.log(`Resolved to: ${resolved.resolvedPath}`);
+ *   return resolved;
+ * });
+ *
+ * const resolved = await Effect.runPromise(Effect.provide(program, NodeLayer));
+ * ```
+ *
+ * @see {@link getTypeEntries} to discover all entry points
+ * @see {@link TypeResolver} for the underlying resolution service
+ *
+ * @public
+ */
+declare const resolveImport: (pkg: PackageSpec, specifier: string) => Effect.Effect<ResolvedModule, CacheError | ParseError | ResolutionError, CacheService | TypeResolver>;
+
+/**
+ * Resolve a version reference to a concrete, pinned version string.
+ *
+ * @remarks
+ * Accepts any npm-style version reference — `"latest"`, a semver range
+ * like `"^1.0.0"`, or an exact version like `"3.23.8"` — and queries the
+ * {@link PackageFetcher} (backed by the jsDelivr API) to determine the
+ * matching published version.
+ *
+ * @param name - The npm package name (e.g. `"zod"`).
+ * @param ref - A version reference: `"latest"`, a semver range, or an exact version.
+ * @returns An Effect that succeeds with the resolved version string (e.g. `"3.23.8"`).
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import { TypeRegistry } from "type-registry-effect";
+ * import { NodeLayer } from "type-registry-effect/node";
+ *
+ * const program = Effect.gen(function* () {
+ *   const version = yield* TypeRegistry.resolveVersion("zod", "latest");
+ *   console.log(`Latest zod version: ${version}`);
+ *   return version;
+ * });
+ *
+ * const version = await Effect.runPromise(Effect.provide(program, NodeLayer));
+ * ```
+ *
+ * @see {@link PackageFetcher} for the underlying network service
+ *
+ * @public
+ */
+declare const resolveVersion: (name: string, ref: string) => Effect.Effect<string, NetworkError | PackageNotFoundError, PackageFetcher>;
+
+/**
+ * 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>;
+
+export declare namespace TypeRegistry {
+    export {
+        hasCached,
+        fetchAndCache,
+        getPackageVFS,
+        getVFS,
+        resolveImport,
+        getTypeEntries,
+        resolveVersion,
+        clearCache
+    }
+}
+
+/**
+ * Union of all error types that can be raised by the type-registry-effect package.
+ *
+ * @remarks
+ * `TypeRegistryError` is a discriminated union over the `_tag` field. Each
+ * variant corresponds to a specific failure mode:
+ *
+ * - `"CacheError"` -- disk cache operations
+ * - `"NetworkError"` -- HTTP requests to the CDN
+ * - `"PackageNotFoundError"` -- missing packages or versions
+ * - `"ParseError"` -- schema validation / JSON parsing
+ * - `"ResolutionError"` -- import specifier resolution
+ * - `"TimeoutError"` -- operation time limits
+ *
+ * Use `Effect.catchTags` to exhaustively handle all variants, or
+ * `Effect.catchTag` for selective handling of individual error types.
+ *
+ * @public
+ */
+export declare type TypeRegistryError = CacheError | NetworkError | PackageNotFoundError | ParseError | ResolutionError | TimeoutError;
+
+/**
+ * Composed layer providing {@link CacheService}, {@link PackageFetcher}, and
+ * {@link TypeResolver} as a single unified layer.
+ *
+ * @remarks
+ * This layer merges {@link CacheServiceLive}, {@link PackageFetcherLive}, and
+ * {@link TypeResolverLive}. It still requires platform-specific
+ * {@link @effect/platform#FileSystem | FileSystem} and
+ * {@link @effect/platform#HttpClient | HttpClient} layers to be provided.
+ * Use the Node.js platform layers to satisfy these requirements:
+ *
+ * @example
+ * ```typescript
+ * import { NodeFileSystem, NodeHttpClient } from "@effect/platform-node";
+ * import { Effect, Layer } from "effect";
+ * import { TypeRegistryLive } from "type-registry-effect";
+ *
+ * const NodeLayer = Layer.mergeAll(NodeFileSystem.layer, NodeHttpClient.layer);
+ * const MainLayer = Layer.provide(TypeRegistryLive, NodeLayer);
+ *
+ * const program = Effect.gen(function* () {
+ *   // All three services are now available
+ *   console.log("registry ready");
+ * });
+ *
+ * Effect.runPromise(Effect.provide(program, MainLayer));
+ * ```
+ *
+ * @see {@link CacheServiceLive}
+ * @see {@link PackageFetcherLive}
+ * @see {@link TypeResolverLive}
+ *
+ * @public
+ */
+export declare const TypeRegistryLive: Layer.Layer<CacheService | PackageFetcher | TypeResolver, never, FileSystem.FileSystem | HttpClient.HttpClient>;
+
+/**
+ * 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>;
+
+/**
+ * Pure {@link TypeResolver} layer with no external dependencies.
+ *
+ * @remarks
+ * Resolution is performed synchronously using only the data present in the
+ * supplied `package.json`. The resolution order is:
+ *
+ * 1. `exports` map (`"types"` condition, then `"import"` / `"default"`)
+ * 2. `typesVersions["*"]` with wildcard pattern matching
+ * 3. Top-level `types` or `typings` fields
+ * 4. Conventional extension swapping (`.js` to `.d.ts`) and `index.d.ts`
+ *    fallback
+ *
+ * @see {@link TypeResolver}
+ *
+ * @public
+ */
+export declare const TypeResolverLive: Layer.Layer<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 declare namespace VirtualPackage {
+    export {
+        VirtualPackage_2 as VirtualPackage
+    }
+}
+
+/**
+ * Creates virtual npm packages from TypeScript declaration content for
+ * inclusion in a {@link VirtualFileSystem} without fetching from the CDN.
+ *
+ * @remarks
+ * `VirtualPackage` is useful when you have locally-generated `.d.ts` files —
+ * for example, output from API Extractor, hand-written ambient declarations, or
+ * declaration files bundled alongside your own packages — and want to inject
+ * them into the same VFS that TypeRegistry builds from remote packages.
+ *
+ * Instances are **transient**: they are not persisted to the disk cache and
+ * live only as long as the VFS they produce. Call {@link VirtualPackage.generateVfs}
+ * to obtain a VFS that can be merged with other VFS maps.
+ *
+ * @see {@link VirtualFileSystem} for the VFS type consumed by TypeScript tooling
+ *
+ * @public
+ */
+declare class VirtualPackage_2 {
+    readonly name: string;
+    readonly version: string;
+    private readonly entries;
+    constructor(name: string, version: string, entries: Map<string, string>);
+    /**
+     * Single-entry convenience factory.
+     *
+     * Creates a virtual package whose sole entry point is `index.d.ts`.
+     *
+     * @param name - Package name (e.g. `"@my-org/api-types"`).
+     * @param version - Semver version string (e.g. `"1.0.0"`).
+     * @param declarations - The full TypeScript declaration source for `index.d.ts`.
+     * @returns A new {@link VirtualPackage} instance.
+     *
+     * @example
+     * ```typescript
+     * import type { VirtualFileSystem } from "type-registry-effect";
+     * import { VirtualPackage } from "type-registry-effect";
+     *
+     * const declarations = `
+     *   export interface User {
+     *     id: string;
+     *     name: string;
+     *   }
+     * `;
+     *
+     * const pkg = VirtualPackage.create("@my-org/api-types", "1.0.0", declarations);
+     * const vfs: VirtualFileSystem = pkg.generateVfs();
+     * console.log([...vfs.keys()]);
+     * // ["node_modules/@my-org/api-types/package.json",
+     * //  "node_modules/@my-org/api-types/index.d.ts"]
+     * ```
+     *
+     * @public
+     */
+    static create(name: string, version: string, declarations: string): VirtualPackage_2;
+    /**
+     * Multi-entry factory.
+     *
+     * Creates a virtual package with multiple `.d.ts` entry point files,
+     * producing a `package.json` that uses the `exports` map.
+     *
+     * @param name - Package name.
+     * @param version - Semver version string.
+     * @param entries - Map of file names (e.g. `"index.d.ts"`, `"testing.d.ts"`)
+     *   to their declaration source content.
+     * @returns A new {@link VirtualPackage} instance.
+     *
+     * @example
+     * ```typescript
+     * import type { VirtualFileSystem } from "type-registry-effect";
+     * import { VirtualPackage } from "type-registry-effect";
+     *
+     * const entries = new Map<string, string>([
+     *   ["index.d.ts", "export declare function run(): void;"],
+     *   ["testing.d.ts", "export declare function mock(): void;"],
+     * ]);
+     *
+     * const pkg = VirtualPackage.createMultiEntry("@my-org/sdk", "2.0.0", entries);
+     * const vfs: VirtualFileSystem = pkg.generateVfs();
+     * console.log([...vfs.keys()]);
+     * // ["node_modules/@my-org/sdk/package.json",
+     * //  "node_modules/@my-org/sdk/index.d.ts",
+     * //  "node_modules/@my-org/sdk/testing.d.ts"]
+     * ```
+     *
+     * @public
+     */
+    static createMultiEntry(name: string, version: string, entries: Map<string, string>): VirtualPackage_2;
+    /**
+     * Load a single `.d.ts` file from disk and create a virtual package from it.
+     *
+     * @remarks
+     * Reads the file synchronously with `node:fs`. The resulting package has a
+     * single `index.d.ts` entry whose content matches the file on disk.
+     *
+     * @param name - Package name.
+     * @param version - Semver version string.
+     * @param filePath - Absolute or relative path to a `.d.ts` file.
+     * @returns A new {@link VirtualPackage} instance.
+     *
+     * @example
+     * ```typescript
+     * import type { VirtualFileSystem } from "type-registry-effect";
+     * import { VirtualPackage } from "type-registry-effect";
+     *
+     * const pkg = VirtualPackage.fromFile(
+     *   "@my-org/api-types",
+     *   "1.0.0",
+     *   "./dist/api-types.d.ts",
+     * );
+     * const vfs: VirtualFileSystem = pkg.generateVfs();
+     * ```
+     *
+     * @public
+     */
+    static fromFile(name: string, version: string, filePath: string): VirtualPackage_2;
+    /**
+     * Generate the full {@link VirtualFileSystem}: a synthetic `package.json`
+     * plus all entry `.d.ts` files, with every path prefixed by
+     * `node_modules/<name>/`.
+     *
+     * @returns A {@link VirtualFileSystem} map ready to be merged with other VFS maps.
+     *
+     * @example
+     * ```typescript
+     * import type { VirtualFileSystem } from "type-registry-effect";
+     * import { VirtualPackage } from "type-registry-effect";
+     *
+     * const pkg = VirtualPackage.create("my-types", "1.0.0", "export type Foo = string;");
+     * const vfs: VirtualFileSystem = pkg.generateVfs();
+     *
+     * for (const [path, content] of vfs) {
+     *   console.log(`${path} (${content.length} chars)`);
+     * }
+     * ```
+     *
+     * @public
+     */
+    generateVfs(): VirtualFileSystem;
+    /**
+     * Generate synthetic `package.json` content for the virtual package.
+     *
+     * @remarks
+     * Uses the `types` field for single-entry packages and the `exports` map
+     * for multi-entry packages so that TypeScript module resolution works
+     * correctly against the generated VFS.
+     *
+     * @returns The `package.json` content as a JSON string.
+     *
+     * @internal
+     */
+    private generatePackageJson;
+}
+
+export { }