0
# Component ID
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @teambit/component-id
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @teambit/component-id`
10

11
## Core Imports
12

13
```typescript
14
import { ComponentID, type ComponentIdObj } from "@teambit/component-id";
15
```
16

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

19
For CommonJS:
20

21
```javascript
22
const { ComponentID } = require("@teambit/component-id");
23
```
24

25
## Basic Usage
26

27
```typescript
28
import { ComponentID } from "@teambit/component-id";
29

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

33
// Access component properties
34
console.log(id.scope);      // "teambit.component"
35
console.log(id.name);       // "button"
36
console.log(id.namespace);  // "ui"
37
console.log(id.version);    // "1.0.0"
38

39
// Create from object
40
const fromObj = ComponentID.fromObject({
41
  name: "ui/button",
42
  scope: "teambit.component",
43
  version: "1.0.0"
44
});
45

46
// Compare IDs
47
const areEqual = ComponentID.isEqual(id, fromObj);
48
console.log(areEqual); // true
49
```
50

51
## Architecture
52

53
The Component ID library is built around several key concepts:
54

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

62
## Capabilities
63

64
### Component ID Creation
65

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

68
```typescript { .api }
69
class ComponentID {
70
  constructor(legacyComponentId: BitId, _scope?: string);
71
  
72
  // Create from string representation
73
  static fromString(idStr: string, scope?: string): ComponentID;
74
  
75
  // Safe parsing that returns undefined on error
76
  static tryFromString(idStr: string, scope?: string): ComponentID | undefined;
77
  
78
  // Create from plain object
79
  static fromObject(object: ComponentIdObj, scope?: string): ComponentID;
80
  static fromObject(object: Omit<ComponentIdObj, 'scope'>, scope: string): ComponentID;
81
  
82
  // Create from legacy BitId (from @teambit/legacy-bit-id package)
83
  static fromLegacy(legacyId: BitId, scope?: string): ComponentID;
84
  
85
  // Parse legacy string format (deprecated)
86
  static fromLegacyString(idStr: string, scope?: string): ComponentID;
87
}
88

89
interface ComponentIdObj {
90
  name: string;
91
  scope: string;
92
  version?: string;
93
}
94
```
95

96
### Component Properties Access
97

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

100
```typescript { .api }
101
class ComponentID {
102
  // Component scope (required)
103
  get scope(): string;
104
  
105
  // Component name (last segment of full name)
106
  get name(): string;
107
  
108
  // Full component name including namespace
109
  get fullName(): string;
110
  
111
  // Component namespace (all segments except last)
112
  get namespace(): string;
113
  
114
  // Component version
115
  get version(): string;
116
  
117
  // Check if ID has version
118
  hasVersion(): boolean;
119
  
120
  // Access to legacy BitId (deprecated - from @teambit/legacy-bit-id)
121
  get _legacy(): BitId;
122
}
123
```
124

125
### Version Operations
126

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

129
```typescript { .api }
130
class ComponentID {
131
  // Check if component has version
132
  hasVersion(): boolean;
133
  
134
  // Get component version
135
  get version(): string;
136
  
137
  // Create new ID with different version
138
  changeVersion(version: string | undefined): ComponentID;
139
  
140
  // Extract pre-release version data
141
  getVersionPreReleaseData(): null | readonly string[];
142
}
143
```
144

145
### Scope Operations
146

147
Change component scope while preserving other identifier information.
148

149
```typescript { .api }
150
class ComponentID {
151
  // Get current scope
152
  get scope(): string;
153
  
154
  // Create new ID with different scope
155
  changeScope(scopeName: string): ComponentID;
156
}
157
```
158

159
### Serialization
160

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

163
```typescript { .api }
164
class ComponentID {
165
  // Serialize to string
166
  toString(opts?: { ignoreVersion?: boolean; fsCompatible?: boolean }): string;
167
  
168
  // Serialize without version
169
  toStringWithoutVersion(): string;
170
  
171
  // Convert to plain object
172
  toObject(): ComponentIdObj;
173
}
174
```
175

176
### Equality Comparison
177

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

180
```typescript { .api }
181
class ComponentID {
182
  // Instance method for equality comparison
183
  isEqual(id: ComponentID, opts?: { ignoreVersion?: boolean }): boolean;
184
  
185
  // Static methods for comparison
186
  static isEqual(a?: ComponentID, b?: ComponentID, opts?: { ignoreVersion?: boolean }): boolean;
187
  static isEqualObj(a?: ComponentIdObj, b?: ComponentIdObj, opts?: { ignoreVersion?: boolean }): boolean;
188
}
189
```
190

191
### Validation and Utilities
192

193
Validate objects and provide utility functions for working with ComponentIDs.
194

195
```typescript { .api }
196
class ComponentID {
197
  // Type guard for ComponentIdObj
198
  static isValidObject(o: any): o is ComponentIdObj;
199
  
200
  // Sort array of ComponentIDs
201
  static sortIds(ids: ComponentID[]): ComponentID[];
202
}
203
```
204

205
### Error Handling
206

207
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.
208

209
```typescript { .api }
210
// MissingScope exception (internal, not exported)
211
class MissingScope extends Error {
212
  constructor(src: any);
213
  report(): string;
214
}
215
```
216

217
Methods that may throw `MissingScope`:
218
- `ComponentID.fromString()` when no scope provided and string doesn't contain scope
219
- `ComponentID.fromLegacy()` when BitId has no scope and no scope parameter provided
220
- `ComponentID.fromObject()` when object has no scope and no scope parameter provided
221

222
## Types
223

224
```typescript { .api }
225
interface ComponentIdObj {
226
  name: string;
227
  scope: string;
228
  version?: string;
229
}
230
```