0
# Lumino Core Utilities
1

2
Lumino Core Utilities provides essential utility functions and classes for TypeScript/JavaScript applications, particularly those building rich desktop-like web applications. It includes comprehensive JSON type definitions and utilities, MIME data management, promise delegation, secure token generation, and cross-platform random number generation with UUID support.
3

4
## Package Information
5

6
- **Package Name**: @lumino/coreutils
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @lumino/coreutils`
10

11
## Core Imports
12

13
```typescript
14
import { JSONExt, MimeData, PromiseDelegate, Token, Random, UUID } from "@lumino/coreutils";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { JSONExt, MimeData, PromiseDelegate, Token, Random, UUID } = require("@lumino/coreutils");
21
```
22

23
Individual imports:
24

25
```typescript
26
import { JSONValue, JSONObject, JSONExt } from "@lumino/coreutils";
27
import { MimeData } from "@lumino/coreutils";
28
import { PromiseDelegate } from "@lumino/coreutils";
29
import { Token } from "@lumino/coreutils";
30
import { Random } from "@lumino/coreutils";
31
import { UUID } from "@lumino/coreutils";
32
```
33

34
## Basic Usage
35

36
```typescript
37
import { JSONExt, MimeData, PromiseDelegate, Token, Random, UUID } from "@lumino/coreutils";
38

39
// JSON utilities
40
const data = { name: "Alice", age: 30 };
41
const copy = JSONExt.deepCopy(data);
42
const isEmpty = JSONExt.deepEqual(data, JSONExt.emptyObject);
43

44
// MIME data handling
45
const mimeData = new MimeData();
46
mimeData.setData("text/plain", "Hello, World!");
47
mimeData.setData("application/json", JSON.stringify(data));
48

49
// Promise delegation
50
const delegate = new PromiseDelegate<string>();
51
delegate.resolve("Task completed");
52
await delegate.promise; // "Task completed"
53

54
// Secure tokens
55
const userToken = new Token<User>("user-token");
56
const configToken = new Token<Config>("config");
57

58
// Random number generation (cross-platform)
59
const buffer = new Uint8Array(16);
60
Random.getRandomValues(buffer);
61

62
// UUID generation
63
const id = UUID.uuid4(); // "f47ac10b-58cc-4372-a567-0e02b2c3d479"
64
```
65

66
## Architecture
67

68
Lumino Core Utilities is designed with a modular, cross-platform architecture:
69

70
- **JSON System**: Complete type-safe JSON handling with readonly and partial variants
71
- **MIME Management**: Generic data storage system organized by MIME types
72
- **Promise Utilities**: Separation of promise creation from resolution logic
73
- **Token System**: Type-safe runtime tokens for dependency injection and object identity
74
- **Cross-Platform Abstraction**: Unified APIs with platform-optimized implementations
75
- **Fallback Strategy**: Graceful degradation when crypto APIs are unavailable
76

77
## Capabilities
78

79
### JSON Utilities
80

81
Comprehensive type system and utilities for type-safe JSON data manipulation with deep equality, copying, and type checking functions.
82

83
```typescript { .api }
84
namespace JSONExt {
85
  const emptyObject: ReadonlyJSONObject;
86
  const emptyArray: ReadonlyJSONArray;
87
  function isPrimitive(value: ReadonlyPartialJSONValue): value is JSONPrimitive;
88
  function isArray(value: ReadonlyPartialJSONValue): boolean;
89
  function isObject(value: ReadonlyPartialJSONValue): boolean;
90
  function deepEqual(first: ReadonlyPartialJSONValue, second: ReadonlyPartialJSONValue): boolean;
91
  function deepCopy<T extends ReadonlyPartialJSONValue>(value: T): T;
92
}
93
```
94

95
[JSON Utilities](./json-utilities.md)
96

97
### MIME Data Management
98

99
Storage and management system for arbitrary data organized by MIME types, ideal for data transfer within applications.
100

101
```typescript { .api }
102
class MimeData {
103
  types(): string[];
104
  hasData(mime: string): boolean;
105
  getData(mime: string): any | undefined;
106
  setData(mime: string, data: any): void;
107
  clearData(mime: string): void;
108
  clear(): void;
109
}
110
```
111

112
[MIME Data Management](./mime-data.md)
113

114
### Promise Delegation
115

116
Promise wrapper that separates promise creation from resolution logic, useful for complex asynchronous workflows.
117

118
```typescript { .api }
119
class PromiseDelegate<T> {
120
  readonly promise: Promise<T>;
121
  resolve(value: T | PromiseLike<T>): void;
122
  reject(reason: any): void;
123
}
124
```
125

126
[Promise Delegation](./promise-delegation.md)
127

128
### Token System
129

130
Runtime tokens that capture compile-time type information for type-safe object identity and dependency injection.
131

132
```typescript { .api }
133
class Token<T> {
134
  constructor(name: string);
135
  readonly name: string;
136
}
137
```
138

139
[Token System](./token-system.md)
140

141
### Random Number Generation
142

143
Cross-platform random number generation with cryptographically strong fallbacks and unified API across browser and Node.js environments.
144

145
```typescript { .api }
146
namespace Random {
147
  const getRandomValues: (buffer: Uint8Array) => void;
148
}
149

150
function fallbackRandomValues(buffer: Uint8Array): void;
151
```
152

153
[Random Number Generation](./random-generation.md)
154

155
### UUID Generation
156

157
RFC 4122 compliant UUID v4 generation with cryptographically strong randomness and cross-platform support.
158

159
```typescript { .api }
160
namespace UUID {
161
  const uuid4: () => string;
162
}
163

164
function uuid4Factory(
165
  getRandomValues: (bytes: Uint8Array) => void
166
): () => string;
167
```
168

169
[UUID Generation](./uuid-generation.md)
170

171
## Types
172

173
```typescript { .api }
174
// JSON Types
175
type JSONPrimitive = boolean | number | string | null;
176
type JSONValue = JSONPrimitive | JSONObject | JSONArray;
177
interface JSONObject {
178
  [key: string]: JSONValue;
179
}
180
interface JSONArray extends Array<JSONValue> {}
181

182
// Readonly JSON Types
183
type ReadonlyJSONValue = JSONPrimitive | ReadonlyJSONObject | ReadonlyJSONArray;
184
interface ReadonlyJSONObject {
185
  readonly [key: string]: ReadonlyJSONValue;
186
}
187
interface ReadonlyJSONArray extends ReadonlyArray<ReadonlyJSONValue> {}
188

189
// Partial JSON Types (allows undefined)
190
type PartialJSONValue = JSONPrimitive | PartialJSONObject | PartialJSONArray;
191
interface PartialJSONObject {
192
  [key: string]: PartialJSONValue | undefined;
193
}
194
interface PartialJSONArray extends Array<PartialJSONValue> {}
195

196
// Readonly Partial JSON Types
197
type ReadonlyPartialJSONValue = JSONPrimitive | ReadonlyPartialJSONObject | ReadonlyPartialJSONArray;
198
interface ReadonlyPartialJSONObject {
199
  readonly [key: string]: ReadonlyPartialJSONValue | undefined;
200
}
201
interface ReadonlyPartialJSONArray extends ReadonlyArray<ReadonlyPartialJSONValue> {}
202
```