@mikesaintsg/core 0.0.1 → 0.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +320 -365
- package/dist/index.d.ts +232 -548
- package/dist/index.js +162 -753
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,365 +1,320 @@
|
|
|
1
|
-
# @mikesaintsg/core
|
|
2
|
-
|
|
3
|
-
> Shared types, contracts, bridge functions
|
|
4
|
-
|
|
5
|
-
[ for guidelines.
|
|
1
|
+
# @mikesaintsg/core
|
|
2
|
+
|
|
3
|
+
> **Shared types, contracts, and bridge functions for the @mikesaintsg ecosystem.**
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@mikesaintsg/core)
|
|
6
|
+
[](https://bundlephobia.com/package/@mikesaintsg/core)
|
|
7
|
+
[](LICENSE)
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Features
|
|
12
|
+
|
|
13
|
+
- ✅ **Shared Types** — Contracts used across multiple packages
|
|
14
|
+
- ✅ **Result Pattern** — Functional error handling (`ok`, `err`, `map`, `chain`)
|
|
15
|
+
- ✅ **Bridge Functions** — Connect packages without circular dependencies
|
|
16
|
+
- ✅ **Adapter Interfaces** — Embedding, tool format, persistence, and policy adapters
|
|
17
|
+
- ✅ **Base Error Class** — `EcosystemError` for all package-specific errors
|
|
18
|
+
- ✅ **Content Hashing** — SHA-256 based deduplication support
|
|
19
|
+
- ✅ **Zero dependencies** — Built on native platform APIs
|
|
20
|
+
- ✅ **TypeScript first** — Full type safety with generics
|
|
21
|
+
- ✅ **Tree-shakeable** — ESM-only, import what you need
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## Installation
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
npm install @mikesaintsg/core
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## Quick Start
|
|
34
|
+
|
|
35
|
+
### Result Pattern
|
|
36
|
+
|
|
37
|
+
```ts
|
|
38
|
+
import { ok, err, isOk, map, chain } from '@mikesaintsg/core'
|
|
39
|
+
import type { Result } from '@mikesaintsg/core'
|
|
40
|
+
|
|
41
|
+
// Create results
|
|
42
|
+
const success = ok(42)
|
|
43
|
+
const failure = err('NOT_FOUND')
|
|
44
|
+
|
|
45
|
+
// Check and unwrap
|
|
46
|
+
if (isOk(success)) {
|
|
47
|
+
console.log(success.value) // 42
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
// Transform values
|
|
51
|
+
const doubled = map(ok(5), x => x * 2) // ok(10)
|
|
52
|
+
|
|
53
|
+
// Chain operations
|
|
54
|
+
function parse(s: string): Result<number, string> {
|
|
55
|
+
const n = parseInt(s, 10)
|
|
56
|
+
return isNaN(n) ? err('PARSE_ERROR') : ok(n)
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
const result = chain(ok('42'), parse) // ok(42)
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
### Content Hashing
|
|
63
|
+
|
|
64
|
+
```ts
|
|
65
|
+
import { computeContentHash } from '@mikesaintsg/core'
|
|
66
|
+
|
|
67
|
+
const hash = await computeContentHash('Hello, world!')
|
|
68
|
+
// 'a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e'
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
### Tool Call Bridge
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
import { createToolCallBridge } from '@mikesaintsg/core'
|
|
75
|
+
|
|
76
|
+
const bridge = createToolCallBridge({
|
|
77
|
+
registry,
|
|
78
|
+
timeout: 30000,
|
|
79
|
+
onError: (error, toolCall) => console.error(error),
|
|
80
|
+
})
|
|
81
|
+
|
|
82
|
+
// Execute single call
|
|
83
|
+
const result = await bridge.execute(toolCall)
|
|
84
|
+
|
|
85
|
+
// Execute multiple calls in parallel
|
|
86
|
+
const results = await bridge.execute([call1, call2, call3])
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## Documentation
|
|
92
|
+
|
|
93
|
+
📚 **[Full API Guide](./guides/core.md)** — Comprehensive documentation with examples
|
|
94
|
+
|
|
95
|
+
### Key Sections
|
|
96
|
+
|
|
97
|
+
- [Introduction](./guides/core.md#introduction) — Value proposition and use cases
|
|
98
|
+
- [Core Concepts](./guides/core.md#core-concepts) — Understand the fundamentals
|
|
99
|
+
- [Result Pattern](./guides/core.md#result-pattern) — Functional error handling
|
|
100
|
+
- [Bridge Interfaces](./guides/core.md#bridge-interfaces) — Cross-package communication
|
|
101
|
+
- [API Reference](./guides/core.md#api-reference) — Complete API documentation
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## API Overview
|
|
106
|
+
|
|
107
|
+
### Result Functions
|
|
108
|
+
|
|
109
|
+
| Function | Description |
|
|
110
|
+
|------------------------------|------------------------------|
|
|
111
|
+
| `ok(value)` | Create a success result |
|
|
112
|
+
| `err(error)` | Create a failure result |
|
|
113
|
+
| `isOk(result)` | Check if result is success |
|
|
114
|
+
| `isErr(result)` | Check if result is failure |
|
|
115
|
+
| `unwrap(result, default)` | Get value or default |
|
|
116
|
+
| `unwrapOrThrow(result)` | Get value or throw error |
|
|
117
|
+
| `map(result, fn)` | Transform success value |
|
|
118
|
+
| `mapErr(result, fn)` | Transform error value |
|
|
119
|
+
| `chain(result, fn)` | Chain results (flatMap) |
|
|
120
|
+
|
|
121
|
+
### Content Hashing
|
|
122
|
+
|
|
123
|
+
| Function | Description |
|
|
124
|
+
|------------------------------|------------------------------|
|
|
125
|
+
| `computeContentHash(text)` | SHA-256 hash for text |
|
|
126
|
+
|
|
127
|
+
### Bridge Helper Functions
|
|
128
|
+
|
|
129
|
+
| Function | Description |
|
|
130
|
+
|------------------------------|-----------------------------------|
|
|
131
|
+
| `isToolCall(value)` | Type guard for ToolCall objects |
|
|
132
|
+
| `shouldSkipFormGuard(...)` | Check if form guard should skip |
|
|
133
|
+
| `formatScoredResult(result)` | Default result formatter |
|
|
134
|
+
|
|
135
|
+
### Factory Functions
|
|
136
|
+
|
|
137
|
+
| Function | Description |
|
|
138
|
+
|-------------------------------------|----------------------------------|
|
|
139
|
+
| `createToolCallBridge(options)` | Connect tool calls to registry |
|
|
140
|
+
| `createRetrievalTool(options)` | Create vectorstore search tool |
|
|
141
|
+
| `createFormDirtyGuard(options)` | Navigation guard for dirty forms |
|
|
142
|
+
| `createSessionPersistence(options)` | Session storage adapter |
|
|
143
|
+
|
|
144
|
+
### Error Handling
|
|
145
|
+
|
|
146
|
+
| Export | Description |
|
|
147
|
+
|------------------------|------------------------------------|
|
|
148
|
+
| `EcosystemError` | Base error class for all packages |
|
|
149
|
+
| `isEcosystemError(e)` | Type guard for ecosystem errors |
|
|
150
|
+
|
|
151
|
+
### Shared Types
|
|
152
|
+
|
|
153
|
+
| Type | Description |
|
|
154
|
+
|-------------------------------------------|---------------------------------------|
|
|
155
|
+
| `Result<T, E>` | Success or failure union |
|
|
156
|
+
| `Ok<T>`, `Err<E>` | Result discriminants |
|
|
157
|
+
| `Unsubscribe` | Cleanup function type |
|
|
158
|
+
| `DestroyFn` | Resource cleanup function |
|
|
159
|
+
| `SubscriptionToHook<T>` | Convert subscriptions to hooks |
|
|
160
|
+
| `Embedding` | Float32Array embedding vector |
|
|
161
|
+
| `ToolCall`, `ToolResult`, `ToolSchema` | Tool-related types |
|
|
162
|
+
| `ScoredResult` | Search result with score |
|
|
163
|
+
| `ContextFrame`, `BuiltContext` | Context management types |
|
|
164
|
+
| `TokenBudgetState`, `TokenBudgetLevel` | Token budget types |
|
|
165
|
+
|
|
166
|
+
### Adapter Interfaces
|
|
167
|
+
|
|
168
|
+
| Interface | Category | Description |
|
|
169
|
+
|-------------------------------------------|---------------|--------------------------------|
|
|
170
|
+
| `EmbeddingAdapterInterface` | Source | Embedding generation |
|
|
171
|
+
| `ToolFormatAdapterInterface` | Transform | Provider tool formatting |
|
|
172
|
+
| `SimilarityAdapterInterface` | Transform | Vector similarity computation |
|
|
173
|
+
| `DeduplicationAdapterInterface` | Transform | Frame deduplication |
|
|
174
|
+
| `TruncationAdapterInterface` | Transform | Context truncation |
|
|
175
|
+
| `PriorityAdapterInterface` | Transform | Frame priority ordering |
|
|
176
|
+
| `RetryAdapterInterface` | Policy | Retry behavior |
|
|
177
|
+
| `RateLimitAdapterInterface` | Policy | Rate limiting |
|
|
178
|
+
| `EmbeddingCacheAdapterInterface` | Enhancement | Embedding caching |
|
|
179
|
+
| `BatchAdapterInterface` | Enhancement | Batch processing |
|
|
180
|
+
| `RerankerAdapterInterface` | Enhancement | Result reranking |
|
|
181
|
+
| `VectorStorePersistenceAdapterInterface` | Persistence | Vector storage |
|
|
182
|
+
|
|
183
|
+
### Minimal Cross-Package Interfaces
|
|
184
|
+
|
|
185
|
+
| Interface | Description |
|
|
186
|
+
|-----------------------------|--------------------------------------|
|
|
187
|
+
| `MinimalDatabaseAccess<T>` | IndexedDB access without dependency |
|
|
188
|
+
| `MinimalStoreAccess<T>` | Store operations interface |
|
|
189
|
+
| `MinimalDirectoryAccess` | OPFS directory access |
|
|
190
|
+
| `MinimalFileAccess` | OPFS file access |
|
|
191
|
+
| `ToolRegistryMinimal` | Tool registry without dependency |
|
|
192
|
+
| `VectorStoreMinimal<T>` | Vector store without dependency |
|
|
193
|
+
| `FormMinimal<T>` | Form state without dependency |
|
|
194
|
+
| `SerializableSession` | Session serialization interface |
|
|
195
|
+
|
|
196
|
+
---
|
|
197
|
+
|
|
198
|
+
## Examples
|
|
199
|
+
|
|
200
|
+
### Result Pattern
|
|
201
|
+
|
|
202
|
+
```ts
|
|
203
|
+
import { ok, err, isOk, unwrap, map, chain } from '@mikesaintsg/core'
|
|
204
|
+
|
|
205
|
+
function divide(a: number, b: number) {
|
|
206
|
+
if (b === 0) return err('DIVISION_BY_ZERO')
|
|
207
|
+
return ok(a / b)
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
const result = divide(10, 2)
|
|
211
|
+
const value = unwrap(result, 0) // 5
|
|
212
|
+
|
|
213
|
+
// Chain operations
|
|
214
|
+
const doubled = chain(divide(10, 2), n => ok(n * 2)) // ok(10)
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
### Custom Error Class
|
|
218
|
+
|
|
219
|
+
```ts
|
|
220
|
+
import { EcosystemError, isEcosystemError } from '@mikesaintsg/core'
|
|
221
|
+
|
|
222
|
+
type StorageErrorCode = 'NOT_FOUND' | 'QUOTA_EXCEEDED' | 'WRITE_FAILED'
|
|
223
|
+
|
|
224
|
+
class StorageError extends EcosystemError {
|
|
225
|
+
readonly code: StorageErrorCode
|
|
226
|
+
|
|
227
|
+
constructor(code: StorageErrorCode, message: string, cause?: Error) {
|
|
228
|
+
super(message, cause)
|
|
229
|
+
this.code = code
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
try {
|
|
234
|
+
throw new StorageError('NOT_FOUND', 'Document not found')
|
|
235
|
+
} catch (error) {
|
|
236
|
+
if (isEcosystemError(error)) {
|
|
237
|
+
console.log(error.code) // 'NOT_FOUND'
|
|
238
|
+
}
|
|
239
|
+
}
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
### Retrieval Tool
|
|
243
|
+
|
|
244
|
+
```ts
|
|
245
|
+
import { createRetrievalTool } from '@mikesaintsg/core'
|
|
246
|
+
|
|
247
|
+
const { schema, handler } = createRetrievalTool({
|
|
248
|
+
vectorStore,
|
|
249
|
+
name: 'search_docs',
|
|
250
|
+
description: 'Search documentation for relevant information',
|
|
251
|
+
defaultLimit: 5,
|
|
252
|
+
scoreThreshold: 0.7,
|
|
253
|
+
})
|
|
254
|
+
|
|
255
|
+
// Register with tool registry
|
|
256
|
+
registry.register(schema, handler)
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
### Session Persistence
|
|
260
|
+
|
|
261
|
+
```ts
|
|
262
|
+
import { createSessionPersistence } from '@mikesaintsg/core'
|
|
263
|
+
|
|
264
|
+
const persistence = createSessionPersistence({
|
|
265
|
+
database,
|
|
266
|
+
storeName: 'chat_sessions',
|
|
267
|
+
autoprune: 7 * 24 * 60 * 60 * 1000, // 7 days
|
|
268
|
+
})
|
|
269
|
+
|
|
270
|
+
await persistence.save('session-1', session)
|
|
271
|
+
const loaded = await persistence.load('session-1')
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
### Form Dirty Guard
|
|
275
|
+
|
|
276
|
+
```ts
|
|
277
|
+
import { createFormDirtyGuard } from '@mikesaintsg/core'
|
|
278
|
+
|
|
279
|
+
const guard = createFormDirtyGuard({
|
|
280
|
+
form,
|
|
281
|
+
confirmFn: (message) => window.confirm(message),
|
|
282
|
+
message: 'You have unsaved changes. Continue?',
|
|
283
|
+
excludePages: ['logout'],
|
|
284
|
+
})
|
|
285
|
+
|
|
286
|
+
router.beforeNavigate(guard)
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
---
|
|
290
|
+
|
|
291
|
+
## Constants
|
|
292
|
+
|
|
293
|
+
| Constant | Value | Description |
|
|
294
|
+
|------------------------------|--------|--------------------------------|
|
|
295
|
+
| `BRIDGE_DEFAULT_TIMEOUT` | 30000 | Default bridge timeout (ms) |
|
|
296
|
+
| `RETRIEVAL_DEFAULT_LIMIT` | 10 | Default retrieval result limit |
|
|
297
|
+
| `RETRIEVAL_MAX_LIMIT` | 100 | Maximum retrieval result limit |
|
|
298
|
+
| `FORM_DIRTY_DEFAULT_MESSAGE` | string | Default form guard message |
|
|
299
|
+
|
|
300
|
+
---
|
|
301
|
+
|
|
302
|
+
## Ecosystem Integration
|
|
303
|
+
|
|
304
|
+
| Package | Integration |
|
|
305
|
+
|--------------------------------|------------------------------------------------|
|
|
306
|
+
| `@mikesaintsg/adapters` | Implements adapter interfaces |
|
|
307
|
+
| `@mikesaintsg/inference` | Uses shared types and bridge functions |
|
|
308
|
+
| `@mikesaintsg/vectorstore` | Uses embedding and persistence interfaces |
|
|
309
|
+
| `@mikesaintsg/contextprotocol` | Uses tool types and registry interface |
|
|
310
|
+
| `@mikesaintsg/contextbuilder` | Uses context frame and budget types |
|
|
311
|
+
| `@mikesaintsg/indexeddb` | Implements MinimalDatabaseAccess |
|
|
312
|
+
| `@mikesaintsg/filesystem` | Implements MinimalDirectoryAccess |
|
|
313
|
+
|
|
314
|
+
See [Integration Guide](./guides/integration.md) for detailed patterns.
|
|
315
|
+
|
|
316
|
+
---
|
|
317
|
+
|
|
318
|
+
## License
|
|
319
|
+
|
|
320
|
+
MIT © [mikesaintsg](https://github.com/mikesaintsg)
|