CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-teambit--component-id

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

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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;
}
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@teambit/component-id@1.2.x
Publish Source
CLI
Badge
tessl/npm-teambit--component-id badge