CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-pnpm--catalogs-config

Utility for parsing and normalizing catalog configurations from pnpm workspace manifests

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

PNPM Catalogs Config

PNPM Catalogs Config is a TypeScript utility library that provides functionality for parsing and normalizing catalog configurations from pnpm workspace manifest files (pnpm-workspace.yaml). It exports a single main function to handle both implicit default catalogs (via the 'catalog' field) and explicit named catalogs (via the 'catalogs' field), with built-in validation to prevent duplicate default catalog definitions.

Package Information

  • Package Name: @pnpm/catalogs.config
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @pnpm/catalogs.config

Core Imports

import { getCatalogsFromWorkspaceManifest } from "@pnpm/catalogs.config";

For CommonJS:

const { getCatalogsFromWorkspaceManifest } = require("@pnpm/catalogs.config");

Basic Usage

import { getCatalogsFromWorkspaceManifest } from "@pnpm/catalogs.config";

// Process workspace manifest with implicit default catalog
const workspaceManifest = {
  catalog: {
    react: "^18.0.0",
    typescript: "^5.0.0"
  },
  catalogs: {
    dev: {
      jest: "^29.0.0",
      eslint: "^8.0.0"
    }
  }
};

const normalizedCatalogs = getCatalogsFromWorkspaceManifest(workspaceManifest);
// Result: 
// {
//   default: { react: "^18.0.0", typescript: "^5.0.0" },
//   dev: { jest: "^29.0.0", eslint: "^8.0.0" }
// }

// Handle missing workspace manifest
const emptyCatalogs = getCatalogsFromWorkspaceManifest(undefined);
// Result: {}

Capabilities

Catalog Normalization

Main function that creates a normalized catalogs configuration from pnpm workspace manifest data.

/**
 * Creates normalized catalogs config from pnpm workspace manifest data
 * @param workspaceManifest - Workspace manifest object with catalog and/or catalogs fields
 * @returns Normalized catalogs object
 */
function getCatalogsFromWorkspaceManifest(
  workspaceManifest: Pick<WorkspaceManifest, 'catalog' | 'catalogs'> | undefined
): Catalogs;

Behavior:

  • Returns empty object {} when workspaceManifest is null or undefined
  • Merges implicit default catalog (from 'catalog' field) with explicit named catalogs (from 'catalogs' field)
  • Sets default catalog from either manifest.catalog or manifest.catalogs.default
  • Validates that default catalog is not defined in both places
  • Throws PnpmError with code 'INVALID_CATALOGS_CONFIGURATION' if validation fails

Types

interface Catalogs {
  /**
   * The default catalog - can be defined via top-level "catalog" field
   * or explicitly named "default" catalog under "catalogs" map
   */
  readonly default?: Catalog;
  
  /**
   * Named catalogs - additional catalog configurations
   */
  readonly [catalogName: string]: Catalog | undefined;
}

interface Catalog {
  readonly [dependencyName: string]: string | undefined;
}

interface WorkspaceManifest {
  /**
   * The default catalog - package manifests may refer to dependencies
   * through the `catalog:default` or `catalog:` specifier
   */
  catalog?: WorkspaceCatalog;
  
  /**
   * Named catalogs - package manifests may refer to dependencies
   * through the `catalog:<name>` specifier
   */
  catalogs?: WorkspaceNamedCatalogs;
}

type WorkspaceCatalog = {
  readonly [dependencyName: string]: string | undefined;
};

type WorkspaceNamedCatalogs = {
  readonly [catalogName: string]: WorkspaceCatalog | undefined;
};

Error Handling

The package throws one specific error when validation fails:

class PnpmError extends Error {
  public readonly code: string;
  public readonly hint?: string;
  constructor(code: string, message: string, opts?: { hint?: string });
}

Error Code:

  • ERR_PNPM_INVALID_CATALOGS_CONFIGURATION: Thrown when both 'catalog' field and 'catalogs.default' field are defined in the workspace manifest

Example Error Handling:

import { getCatalogsFromWorkspaceManifest } from "@pnpm/catalogs.config";

try {
  const catalogs = getCatalogsFromWorkspaceManifest({
    catalog: { react: "^18.0.0" },
    catalogs: {
      default: { vue: "^3.0.0" }  // This will cause an error
    }
  });
} catch (error) {
  if (error.code === 'ERR_PNPM_INVALID_CATALOGS_CONFIGURATION') {
    console.error('Default catalog defined multiple times');
  }
}

Install with Tessl CLI

npx tessl i tessl/npm-pnpm--catalogs-config
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@pnpm/catalogs.config@1000.0.x
Publish Source
CLI
Badge
tessl/npm-pnpm--catalogs-config badge