@pnpm/store-controller-types

import {
  StoreController,
  RequestPackageFunction,
  FetchPackageToStoreFunction,
  PackageResponse,
  BundledManifest
} from "@pnpm/store-controller-types";

const {
  StoreController,
  RequestPackageFunction,
  FetchPackageToStoreFunction,
  PackageResponse,
  BundledManifest
} = require("@pnpm/store-controller-types");

import {
  StoreController,
  RequestPackageFunction,
  FetchPackageToStoreFunction,
  RequestPackageOptions,
  FetchPackageToStoreOptions
} from "@pnpm/store-controller-types";

// Implementing a store controller
class MyStoreController implements StoreController {
  async requestPackage: RequestPackageFunction = async (wantedDependency, options) => {
    // Implementation for requesting packages
    return {
      body: {
        isLocal: false,
        resolution: { type: 'version', version: '1.0.0' },
        id: 'registry.npmjs.org/my-package/1.0.0',
        updated: false
      }
    };
  };

  fetchPackage: FetchPackageToStoreFunction = (opts) => {
    // Implementation for fetching packages
    return {
      filesIndexFile: '/path/to/files-index',
      fetching: async () => ({
        files: { fromStore: false, filenames: [], sideEffects: {} }
      })
    };
  };

  // Other required methods...
  async close() {}
  async prune() {}
  // etc.
}

interface StoreController {
  /** Request and resolve a package, returning metadata and optional fetch function */
  requestPackage: RequestPackageFunction;
  /** Fetch a package to the store, returning files index and fetch promise */
  fetchPackage: FetchPackageToStoreFunction | FetchPackageToStoreFunctionAsync;
  /** Get the files index file path for a package */
  getFilesIndexFilePath: GetFilesIndexFilePath;
  /** Import a package from store to destination directory */
  importPackage: ImportPackageFunctionAsync;
  /** Close the store controller and cleanup resources */
  close: () => Promise<void>;
  /** Prune unused packages from the store */
  prune: (removeAlienFiles?: boolean) => Promise<void>;
  /** Upload a built package to the store */
  upload: UploadPkgToStore;
  /** Clear the resolution cache */
  clearResolutionCache: () => void;
}

type RequestPackageFunction = (
  wantedDependency: WantedDependency & { optional?: boolean },
  options: RequestPackageOptions
) => Promise<PackageResponse>;

interface RequestPackageOptions {
  /** Always try workspace packages first when resolving */
  alwaysTryWorkspacePackages?: boolean;
  /** Information about the current package being processed */
  currentPkg?: {
    id?: PkgResolutionId;
    name?: string;
    resolution?: Resolution;
    version?: string;
  };
  /** Expected package name and version from lockfile */
  expectedPkg?: PkgNameVersion;
  /** Default tag to use when no version is specified */
  defaultTag?: string;
  /** Prefer the lowest satisfying version instead of highest */
  pickLowestVersion?: boolean;
  /** Date when package was published (for filtering) */
  publishedBy?: Date;
  /** Priority for downloading this package */
  downloadPriority: number;
  /** Skip running scripts during installation */
  ignoreScripts?: boolean;
  /** Directory of the current project */
  projectDir: string;
  /** Directory containing the lockfile */
  lockfileDir: string;
  /** Version preferences for resolution */
  preferredVersions: PreferredVersions;
  /** Prefer workspace packages over external packages */
  preferWorkspacePackages?: boolean;
  /** Enable side effects caching */
  sideEffectsCache?: boolean;
  /** Skip fetching the package (resolve only) */
  skipFetch?: boolean;
  /** Update strategy: false (no updates), 'compatible', or 'latest' */
  update?: false | 'compatible' | 'latest';
  /** Workspace packages mapping */
  workspacePackages?: WorkspacePackages;
  /** Force resolution even if cached */
  forceResolve?: boolean;
  /** Supported architectures for native packages */
  supportedArchitectures?: SupportedArchitectures;
  /** Error handler for fetch operations */
  onFetchError?: OnFetchError;
  /** Inject workspace packages into resolution */
  injectWorkspacePackages?: boolean;
  /** Calculate the normalized specifier */
  calcSpecifier?: boolean;
  /** Pinned version information */
  pinnedVersion?: PinnedVersion;
}

interface PackageResponse {
  /** Optional function to fetch package files */
  fetching?: () => Promise<PkgRequestFetchResult>;
  /** Path to the files index file */
  filesIndexFile?: string;
  /** Package resolution and metadata */
  body: {
    /** Whether package is local (workspace) */
    isLocal: boolean;
    /** Whether package can be installed */
    isInstallable?: boolean;
    /** Package resolution information */
    resolution: Resolution;
    /** Package manifest/metadata */
    manifest?: PackageManifest;
    /** Unique package identifier */
    id: PkgResolutionId;
    /** Normalized bare specifier */
    normalizedBareSpecifier?: string;
    /** Whether package was updated */
    updated: boolean;
    /** Package publication timestamp */
    publishedAt?: string;
    /** How package was resolved */
    resolvedVia?: string;
    /** Latest available version */
    latest?: string;
    /** Package alias */
    alias?: string;
  } & (
    {
      isLocal: true;
      resolution: DirectoryResolution;
    } | {
      isLocal: false;
    }
  );
}

type FetchPackageToStoreFunction = (opts: FetchPackageToStoreOptions) => FetchResponse;
type FetchPackageToStoreFunctionAsync = (opts: FetchPackageToStoreOptions) => Promise<FetchResponse>;

interface FetchPackageToStoreOptions {
  /** Fetch the raw package manifest */
  fetchRawManifest?: boolean;
  /** Force refetch even if package exists */
  force: boolean;
  /** Skip running package scripts */
  ignoreScripts?: boolean;
  /** Directory containing the lockfile */
  lockfileDir: string;
  /** Package information to fetch */
  pkg: PkgNameVersion & {
    id: string;
    resolution: Resolution;
  };
  /** Error handler for fetch failures */
  onFetchError?: OnFetchError;
  /** Supported architectures for platform-specific packages */
  supportedArchitectures?: SupportedArchitectures;
}

interface FetchResponse {
  /** Path to the files index file */
  filesIndexFile: string;
  /** Function to execute the actual fetch operation */
  fetching: () => Promise<PkgRequestFetchResult>;
}

interface PkgRequestFetchResult {
  /** Bundled manifest for the package */
  bundledManifest?: BundledManifest;
  /** Package files information */
  files: PackageFilesResponse;
}

type GetFilesIndexFilePath = (opts: Pick<FetchPackageToStoreOptions, 'pkg' | 'ignoreScripts'>) => {
  filesIndexFile: string;
  target: string;
};

type ImportIndexedPackage = (to: string, opts: ImportOptions) => string | undefined;
type ImportIndexedPackageAsync = (to: string, opts: ImportOptions) => Promise<string | undefined>;

interface ImportOptions {
  /** Disable relinking of local directory dependencies */
  disableRelinkLocalDirDeps?: boolean;
  /** Mapping of file paths to their content hashes */
  filesMap: FilesMap;
  /** Force import even if target exists */
  force: boolean;
  /** Source location of the resolved package */
  resolvedFrom: ResolvedFrom;
  /** Keep existing modules directory during import */
  keepModulesDir?: boolean;
}

type FilesMap = Record<string, string>;

type ImportPackageFunction = (
  to: string,
  opts: ImportPackageOpts
) => { isBuilt: boolean, importMethod: undefined | string };

type ImportPackageFunctionAsync = (
  to: string,  
  opts: ImportPackageOpts
) => Promise<{ isBuilt: boolean, importMethod: undefined | string }>;

interface ImportPackageOpts {
  /** Disable relinking of local directory dependencies */
  disableRelinkLocalDirDeps?: boolean;
  /** Whether the package requires building */
  requiresBuild?: boolean;
  /** Cache key for side effects */
  sideEffectsCacheKey?: string;
  /** Package files response information */
  filesResponse: PackageFilesResponse;
  /** Force import even if target exists */
  force: boolean;
  /** Keep existing modules directory during import */
  keepModulesDir?: boolean;
}

type UploadPkgToStore = (builtPkgLocation: string, opts: UploadPkgToStoreOpts) => Promise<void>;

interface UploadPkgToStoreOpts {
  /** Path to the files index file */
  filesIndexFile: string;
  /** Cache key for side effects */
  sideEffectsCacheKey: string;
}

type OnFetchError = (error: Error) => Error;

interface PkgNameVersion {
  /** Package name */
  name?: string;
  /** Package version */
  version?: string;
}

type BundledManifestFunction = () => Promise<BundledManifest | undefined>;

type BundledManifest = Pick<
  DependencyManifest,
  | 'bin'
  | 'bundledDependencies'
  | 'bundleDependencies'
  | 'cpu'
  | 'dependencies'
  | 'directories'
  | 'engines'
  | 'name'
  | 'optionalDependencies'
  | 'os'
  | 'peerDependencies'
  | 'peerDependenciesMeta'
  | 'scripts'
  | 'version'
>;

// From @pnpm/resolver-base (all exports)
export * from '@pnpm/resolver-base';

// From @pnpm/cafs-types (selective exports)
export type {
  PackageFileInfo,
  PackageFilesResponse,
  ImportPackageFunction,
  ImportPackageFunctionAsync
};

type PkgResolutionId = string & { __brand: 'PkgResolutionId' };

interface DirectoryResolution {
  type: 'directory';
  directory: string;
}

interface PreferredVersions {
  [packageName: string]: VersionSelectors;
}

interface VersionSelectors {
  [selector: string]: VersionSelectorWithWeight | VersionSelectorType;
}

interface VersionSelectorWithWeight {
  selectorType: VersionSelectorType;
  weight: number;
}

type VersionSelectorType = 'version' | 'range' | 'tag';

type Resolution = AtomicResolution | VariationsResolution;

type AtomicResolution =
  | TarballResolution
  | DirectoryResolution
  | GitResolution
  | BinaryResolution;

interface TarballResolution {
  type?: undefined;
  tarball: string;
  integrity?: string;
  path?: string;
}

interface GitResolution {
  commit: string;
  repo: string;
  path?: string;
  type: 'git';
}

interface BinaryResolution {
  type: 'binary';
  archive: 'tarball' | 'zip';
  url: string;
  integrity: string;
  bin: string;
  prefix?: string;
}

interface VariationsResolution {
  type: 'variations';
  variants: PlatformAssetResolution[];
}

interface PlatformAssetResolution {
  resolution: AtomicResolution;
  targets: PlatformAssetTarget[];
}

interface PlatformAssetTarget {
  os: string;
  cpu: string;
  libc?: 'musl';
}

type WantedDependency = {
  injected?: boolean;
  prevSpecifier?: string;
} & ({
  alias?: string;
  bareSpecifier: string;
} | {
  alias: string;
  bareSpecifier?: string;
});

type WorkspacePackages = Map<string, WorkspacePackagesByVersion>;

type WorkspacePackagesByVersion = Map<string, WorkspacePackage>;

interface WorkspacePackage {
  rootDir: ProjectRootDir;
  manifest: DependencyManifest;
}

interface PackageFileInfo {
  checkedAt?: number;
  integrity: string;
  mode: number;
  size: number;
}

type ResolvedFrom = 'store' | 'local-dir' | 'remote';

type PackageFilesResponse = {
  resolvedFrom: ResolvedFrom;
  packageImportMethod?: 'auto' | 'hardlink' | 'copy' | 'clone' | 'clone-or-copy';
  sideEffects?: SideEffects;
  requiresBuild: boolean;
} & ({
  unprocessed?: false;
  filesIndex: Record<string, string>;
} | {
  unprocessed: true;
  filesIndex: PackageFiles;
});

type PackageFiles = Record<string, PackageFileInfo>;

type SideEffects = Record<string, SideEffectsDiff>;

interface SideEffectsDiff {
  deleted?: string[];
  added?: PackageFiles;
}

interface SupportedArchitectures {
  os?: string[];
  cpu?: string[];
  libc?: string[];
}

interface DependencyManifest {
  name: string;
  version: string;
  bin?: PackageBin;
  description?: string;
  dependencies?: Dependencies;
  optionalDependencies?: Dependencies;
  peerDependencies?: Dependencies;
  peerDependenciesMeta?: PeerDependenciesMeta;
  scripts?: PackageScripts;
  engines?: object;
  cpu?: string[];
  os?: string[];
  // ... and many other package.json fields
}

interface PackageManifest extends DependencyManifest {
  deprecated?: string;
}

type PinnedVersion = 'none' | 'patch' | 'minor' | 'major';

type ProjectRootDir = string & { __brand: 'ProjectRootDir' };

type Dependencies = Record<string, string>;

type PackageBin = string | { [commandName: string]: string };

type PackageScripts = Record<string, string>;

interface PeerDependenciesMeta {
  [dependencyName: string]: {
    optional?: boolean;
  };
}