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
```