@packall/core 0.1.0 → 0.3.0

package/src/registry.ts

@@ -1,115 +1,116 @@
-/**
- * The registry seam.
- *
- * This is the **only** place in the engine that knows a registry exists.
- * Everything downstream — range resolution, the dependency walk, layout,
- * archiving — is expressed against these three operations, so swapping npm for
- * something else means implementing this interface and nothing more.
- *
- * `@packall/registry-npm` provides the implementation that speaks the plain
- * npm registry protocol, which is what Artifactory, Nexus, Verdaccio, GitHub
- * Packages and registry.npmjs.org all serve.
- */
-import * as Context from "effect/Context"
-import type * as Effect from "effect/Effect"
-import type { BundlerError } from "./errors.js"
-
-/** Where the tarball lives and how to prove it arrived intact. */
-export type PackageDist = {
-  readonly tarball: string
-  /** SRI string, e.g. `sha512-...`. Preferred over `shasum`. */
-  readonly integrity?: string | undefined
-  /** Legacy hex sha1. Still the only checksum on very old versions. */
-  readonly shasum?: string | undefined
-  readonly unpackedSize?: number | undefined
-  readonly fileCount?: number | undefined
-}
-
-/**
- * A single published version, as the registry describes it.
- *
- * This is a narrowed view of a package.json — only the fields that affect what
- * has to be downloaded. Unknown fields are ignored rather than rejected,
- * because registries add metadata over time and a bundler that breaks on new
- * metadata is worse than useless.
- */
-export type PackageManifest = {
-  readonly name: string
-  readonly version: string
-
-  readonly dependencies?: Readonly<Record<string, string>> | undefined
-  readonly optionalDependencies?: Readonly<Record<string, string>> | undefined
-  readonly peerDependencies?: Readonly<Record<string, string>> | undefined
-  readonly peerDependenciesMeta?:
-    | Readonly<Record<string, { readonly optional?: boolean | undefined }>>
-    | undefined
-  readonly devDependencies?: Readonly<Record<string, string>> | undefined
-  readonly bundleDependencies?: ReadonlyArray<string> | undefined
-
-  /** Platform constraints, used when `--platform` narrows optional deps. */
-  readonly os?: ReadonlyArray<string> | undefined
-  readonly cpu?: ReadonlyArray<string> | undefined
-  readonly libc?: ReadonlyArray<string> | undefined
-
-  readonly deprecated?: string | undefined
-
-  readonly dist: PackageDist
-}
-
-/** Everything the registry knows about one package. */
-export type Packument = {
-  readonly name: string
-  /** `{ latest: "1.2.3", next: "2.0.0-beta.1" }` */
-  readonly distTags: Readonly<Record<string, string>>
-  /** Every published version, keyed by version string. */
-  readonly versions: Readonly<Record<string, PackageManifest>>
-}
-
-export declare namespace Registry {
-  /** The set of operations a registry backend has to provide. */
-  export type Service = {
-    /** Short identifier for the manifest and for error messages, e.g. `"npm"`. */
-    readonly kind: string
-
-    /**
-     * The registry URL that will actually be used for a given package, after
-     * per-scope configuration is applied. Used for reporting only.
-     */
-    readonly registryFor: (packageName: string) => string
-
-    /**
-     * Cheap liveness check, run once before any real work.
-     *
-     * This is what turns "hangs forever behind a dead VPN" into a five-second
-     * error naming the host we could not reach.
-     */
-    readonly preflight: Effect.Effect<void, BundlerError>
-
-    /**
-     * Full metadata for a package. Implementations are expected to memoise:
-     * the dependency walk asks for the same popular packages repeatedly.
-     */
-    readonly packument: (packageName: string) => Effect.Effect<Packument, BundlerError>
-
-    /** Fetches the tarball bytes for one published version. */
-    readonly download: (manifest: PackageManifest) => Effect.Effect<Uint8Array, BundlerError>
-  }
-}
-
-/**
- * Service tag for the registry backend.
- *
- * @example
- * ```ts
- * import { Effect } from "effect"
- * import { Registry } from "@packall/core"
- *
- * const program = Effect.gen(function*() {
- *   const registry = yield* Registry
- *   return yield* registry.packument("lodash")
- * })
- * ```
- */
-export class Registry extends Context.Service<Registry, Registry.Service>()(
-  "@packall/core/Registry"
-) {}
+/**
+ * The registry seam.
+ *
+ * This is the **only** place in the engine that knows a registry exists.
+ * Everything downstream — range resolution, the dependency walk, layout,
+ * archiving — is expressed against these three operations, so swapping npm for
+ * something else means implementing this interface and nothing more.
+ *
+ * `@packall/registry-npm` provides the implementation that speaks the plain
+ * npm registry protocol, which is what Artifactory, Nexus, Verdaccio, GitHub
+ * Packages and registry.npmjs.org all serve.
+ */
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+
+import type { BundlerError } from "./errors.js";
+
+/** Where the tarball lives and how to prove it arrived intact. */
+export type PackageDist = {
+	readonly tarball: string;
+	/** SRI string, e.g. `sha512-...`. Preferred over `shasum`. */
+	readonly integrity?: string | undefined;
+	/** Legacy hex sha1. Still the only checksum on very old versions. */
+	readonly shasum?: string | undefined;
+	readonly unpackedSize?: number | undefined;
+	readonly fileCount?: number | undefined;
+};
+
+/**
+ * A single published version, as the registry describes it.
+ *
+ * This is a narrowed view of a package.json — only the fields that affect what
+ * has to be downloaded. Unknown fields are ignored rather than rejected,
+ * because registries add metadata over time and a bundler that breaks on new
+ * metadata is worse than useless.
+ */
+export type PackageManifest = {
+	readonly name: string;
+	readonly version: string;
+
+	readonly dependencies?: Readonly<Record<string, string>> | undefined;
+	readonly optionalDependencies?: Readonly<Record<string, string>> | undefined;
+	readonly peerDependencies?: Readonly<Record<string, string>> | undefined;
+	readonly peerDependenciesMeta?:
+		| Readonly<Record<string, { readonly optional?: boolean | undefined }>>
+		| undefined;
+	readonly devDependencies?: Readonly<Record<string, string>> | undefined;
+	readonly bundleDependencies?: ReadonlyArray<string> | undefined;
+
+	/** Platform constraints, used when `--platform` narrows optional deps. */
+	readonly os?: ReadonlyArray<string> | undefined;
+	readonly cpu?: ReadonlyArray<string> | undefined;
+	readonly libc?: ReadonlyArray<string> | undefined;
+
+	readonly deprecated?: string | undefined;
+
+	readonly dist: PackageDist;
+};
+
+/** Everything the registry knows about one package. */
+export type Packument = {
+	readonly name: string;
+	/** `{ latest: "1.2.3", next: "2.0.0-beta.1" }` */
+	readonly distTags: Readonly<Record<string, string>>;
+	/** Every published version, keyed by version string. */
+	readonly versions: Readonly<Record<string, PackageManifest>>;
+};
+
+export declare namespace Registry {
+	/** The set of operations a registry backend has to provide. */
+	export type Service = {
+		/** Short identifier for the manifest and for error messages, e.g. `"npm"`. */
+		readonly kind: string;
+
+		/**
+		 * The registry URL that will actually be used for a given package, after
+		 * per-scope configuration is applied. Used for reporting only.
+		 */
+		readonly registryFor: (packageName: string) => string;
+
+		/**
+		 * Cheap liveness check, run once before any real work.
+		 *
+		 * This is what turns "hangs forever behind a dead VPN" into a five-second
+		 * error naming the host we could not reach.
+		 */
+		readonly preflight: Effect.Effect<void, BundlerError>;
+
+		/**
+		 * Full metadata for a package. Implementations are expected to memoise:
+		 * the dependency walk asks for the same popular packages repeatedly.
+		 */
+		readonly packument: (packageName: string) => Effect.Effect<Packument, BundlerError>;
+
+		/** Fetches the tarball bytes for one published version. */
+		readonly download: (manifest: PackageManifest) => Effect.Effect<Uint8Array, BundlerError>;
+	};
+}
+
+/**
+ * Service tag for the registry backend.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Registry } from "@packall/core"
+ *
+ * const program = Effect.gen(function*() {
+ *   const registry = yield* Registry
+ *   return yield* registry.packument("lodash")
+ * })
+ * ```
+ */
+export class Registry extends Context.Service<Registry, Registry.Service>()(
+	"@packall/core/Registry",
+) {}