@packall/core 0.0.1 → 0.1.0

package/src/{Registry.ts → registry.ts}

@@ -1,121 +1,115 @@
-/**
- * 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"
-
-/**
- * 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 interface 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
-}
-
-/** Where the tarball lives and how to prove it arrived intact. */
-export interface 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
-}
-
-/** Everything the registry knows about one package. */
-export interface 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>>
-}
-
-/** The set of operations a registry backend has to provide. */
-export interface RegistryService {
-  /** 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, RegistryService>()(
-  "@packall/core/Registry"
-) {}
-
-/** Extracts the dist-tag mapping, defaulting sensibly when a registry omits it. */
-export const resolveDistTag = (packument: Packument, tag: string): string | undefined =>
-  packument.distTags[tag]
-
-/** All published version strings, in registry order. */
-export const publishedVersions = (packument: Packument): ReadonlyArray<string> =>
-  Object.keys(packument.versions)
+/**
+ * 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"
+) {}