or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-teambit--component-id

A TypeScript library for programmatic handling and manipulation of Bit component identifiers

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@teambit/component-id@1.2.x

To install, run

npx @tessl/cli install tessl/npm-teambit--component-id@1.2.0

index.mddocs/

Component ID

Component ID is a TypeScript library that provides programmatic handling and manipulation of Bit component identifiers within the Bit ecosystem. It offers a comprehensive ComponentID class that wraps legacy BitId functionality while providing modern APIs for parsing, serializing, and manipulating component identifiers that include scope, name, version, and namespace information.

Package Information

  • Package Name: @teambit/component-id
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @teambit/component-id

Core Imports

import { ComponentID, type ComponentIdObj } from "@teambit/component-id";

Note: The MissingScope exception and BitId type are used internally but not exported. BitId comes from the @teambit/legacy-bit-id package.

For CommonJS:

const { ComponentID } = require("@teambit/component-id");

Basic Usage

import { ComponentID } from "@teambit/component-id";

// Parse component ID from string
const id = ComponentID.fromString("teambit.component/ui/button@1.0.0");

// Access component properties
console.log(id.scope);      // "teambit.component"
console.log(id.name);       // "button"
console.log(id.namespace);  // "ui"
console.log(id.version);    // "1.0.0"

// Create from object
const fromObj = ComponentID.fromObject({
  name: "ui/button",
  scope: "teambit.component",
  version: "1.0.0"
});

// Compare IDs
const areEqual = ComponentID.isEqual(id, fromObj);
console.log(areEqual); // true

Architecture

The Component ID library is built around several key concepts:

  • ComponentID Class: Main class providing modern API for component identification
  • Legacy Integration: Wraps BitId from @teambit/legacy-bit-id for backward compatibility
  • String Parsing: Supports parsing component IDs from string representations
  • Object Serialization: Convert between ComponentID instances and plain objects
  • Version Management: Handle versioned and unversioned component identifiers
  • Scope Operations: Change component scope while preserving other identifier parts

Capabilities

Component ID Creation

Create ComponentID instances from various sources including strings, objects, and legacy BitId instances.

class ComponentID {
  constructor(legacyComponentId: BitId, _scope?: string);
  
  // Create from string representation
  static fromString(idStr: string, scope?: string): ComponentID;
  
  // Safe parsing that returns undefined on error
  static tryFromString(idStr: string, scope?: string): ComponentID | undefined;
  
  // Create from plain object
  static fromObject(object: ComponentIdObj, scope?: string): ComponentID;
  static fromObject(object: Omit<ComponentIdObj, 'scope'>, scope: string): ComponentID;
  
  // Create from legacy BitId (from @teambit/legacy-bit-id package)
  static fromLegacy(legacyId: BitId, scope?: string): ComponentID;
  
  // Parse legacy string format (deprecated)
  static fromLegacyString(idStr: string, scope?: string): ComponentID;
}

interface ComponentIdObj {
  name: string;
  scope: string;
  version?: string;
}

Component Properties Access

Access various parts of the component identifier including scope, name, namespace, and version information.

class ComponentID {
  // Component scope (required)
  get scope(): string;
  
  // Component name (last segment of full name)
  get name(): string;
  
  // Full component name including namespace
  get fullName(): string;
  
  // Component namespace (all segments except last)
  get namespace(): string;
  
  // Component version
  get version(): string;
  
  // Check if ID has version
  hasVersion(): boolean;
  
  // Access to legacy BitId (deprecated - from @teambit/legacy-bit-id)
  get _legacy(): BitId;
}

Version Operations

Manage component versions including checking for version presence and extracting pre-release data.

class ComponentID {
  // Check if component has version
  hasVersion(): boolean;
  
  // Get component version
  get version(): string;
  
  // Create new ID with different version
  changeVersion(version: string | undefined): ComponentID;
  
  // Extract pre-release version data
  getVersionPreReleaseData(): null | readonly string[];
}

Scope Operations

Change component scope while preserving other identifier information.

class ComponentID {
  // Get current scope
  get scope(): string;
  
  // Create new ID with different scope
  changeScope(scopeName: string): ComponentID;
}

Serialization

Convert ComponentID instances to string and object representations for storage or transmission.

class ComponentID {
  // Serialize to string
  toString(opts?: { ignoreVersion?: boolean; fsCompatible?: boolean }): string;
  
  // Serialize without version
  toStringWithoutVersion(): string;
  
  // Convert to plain object
  toObject(): ComponentIdObj;
}

Equality Comparison

Compare ComponentID instances and objects with flexible options for version handling.

class ComponentID {
  // Instance method for equality comparison
  isEqual(id: ComponentID, opts?: { ignoreVersion?: boolean }): boolean;
  
  // Static methods for comparison
  static isEqual(a?: ComponentID, b?: ComponentID, opts?: { ignoreVersion?: boolean }): boolean;
  static isEqualObj(a?: ComponentIdObj, b?: ComponentIdObj, opts?: { ignoreVersion?: boolean }): boolean;
}

Validation and Utilities

Validate objects and provide utility functions for working with ComponentIDs.

class ComponentID {
  // Type guard for ComponentIdObj
  static isValidObject(o: any): o is ComponentIdObj;
  
  // Sort array of ComponentIDs
  static sortIds(ids: ComponentID[]): ComponentID[];
}

Error Handling

The ComponentID methods may throw errors when required parameters are missing. The most common error is MissingScope, which occurs when creating a ComponentID without providing sufficient scope information.

// MissingScope exception (internal, not exported)
class MissingScope extends Error {
  constructor(src: any);
  report(): string;
}

Methods that may throw MissingScope:

  • ComponentID.fromString() when no scope provided and string doesn't contain scope
  • ComponentID.fromLegacy() when BitId has no scope and no scope parameter provided
  • ComponentID.fromObject() when object has no scope and no scope parameter provided

Types

interface ComponentIdObj {
  name: string;
  scope: string;
  version?: string;
}