@mikesaintsg/core 0.0.2 → 0.0.4

package/README.md

@@ -13,7 +13,9 @@
 - ✅ **Shared Types** — Contracts used across multiple packages
 - ✅ **Result Pattern** — Functional error handling (`ok`, `err`, `map`, `chain`)
 - ✅ **Bridge Functions** — Connect packages without circular dependencies
-- ✅ **Interface Definitions** — Embedding, tool format, and persistence adapters
+- ✅ **Adapter Interfaces** — Embedding, tool format, persistence, and policy adapters
+- ✅ **Base Error Class** — `EcosystemError` for all package-specific errors
+- ✅ **Content Hashing** — SHA-256 based deduplication support
 - ✅ **Zero dependencies** — Built on native platform APIs
 - ✅ **TypeScript first** — Full type safety with generics
 - ✅ **Tree-shakeable** — ESM-only, import what you need
@@ -30,6 +32,8 @@ npm install @mikesaintsg/core
 
 ## Quick Start
 
+### Result Pattern
+
 ```ts
 import { ok, err, isOk, map, chain } from '@mikesaintsg/core'
 import type { Result } from '@mikesaintsg/core'
@@ -55,6 +59,33 @@ function parse(s: string): Result<number, string> {
 const result = chain(ok('42'), parse) // ok(42)
 ```
 
+### Content Hashing
+
+```ts
+import { computeContentHash } from '@mikesaintsg/core'
+
+const hash = await computeContentHash('Hello, world!')
+// 'a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e'
+```
+
+### Tool Call Bridge
+
+```ts
+import { createToolCallBridge } from '@mikesaintsg/core'
+
+const bridge = createToolCallBridge({
+  registry,
+  timeout: 30000,
+  onError: (error, toolCall) => console.error(error),
+})
+
+// Execute single call
+const result = await bridge.execute(toolCall)
+
+// Execute multiple calls in parallel
+const results = await bridge.execute([call1, call2, call3])
+```
+
 ---
 
 ## Documentation
@@ -64,7 +95,6 @@ const result = chain(ok('42'), parse) // ok(42)
 ### Key Sections
 
 - [Introduction](./guides/core.md#introduction) — Value proposition and use cases
-- [Quick Start](./guides/core.md#quick-start) — Get started in minutes
 - [Core Concepts](./guides/core.md#core-concepts) — Understand the fundamentals
 - [Result Pattern](./guides/core.md#result-pattern) — Functional error handling
 - [Bridge Interfaces](./guides/core.md#bridge-interfaces) — Cross-package communication
@@ -76,17 +106,33 @@ const result = chain(ok('42'), parse) // ok(42)
 
 ### Result Functions
 
-| Function                  | Description                |
-|---------------------------|----------------------------|
-| `ok(value)`               | Create a success result    |
-| `err(error)`              | Create a failure result    |
-| `isOk(result)`            | Check if result is success |
-| `isErr(result)`           | Check if result is failure |
-| `unwrap(result, default)` | Get value or default       |
-| `map(result, fn)`         | Transform success value    |
-| `chain(result, fn)`       | Chain results (flatMap)    |
+| Function                     | Description                  |
+|------------------------------|------------------------------|
+| `ok(value)`                  | Create a success result      |
+| `err(error)`                 | Create a failure result      |
+| `isOk(result)`               | Check if result is success   |
+| `isErr(result)`              | Check if result is failure   |
+| `unwrap(result, default)`    | Get value or default         |
+| `unwrapOrThrow(result)`      | Get value or throw error     |
+| `map(result, fn)`            | Transform success value      |
+| `mapErr(result, fn)`         | Transform error value        |
+| `chain(result, fn)`          | Chain results (flatMap)      |
+
+### Content Hashing
 
-### Bridge Functions
+| Function                     | Description                  |
+|------------------------------|------------------------------|
+| `computeContentHash(text)`   | SHA-256 hash for text        |
+
+### Bridge Helper Functions
+
+| Function                     | Description                       |
+|------------------------------|-----------------------------------|
+| `isToolCall(value)`          | Type guard for ToolCall objects   |
+| `shouldSkipFormGuard(...)`   | Check if form guard should skip   |
+| `formatScoredResult(result)` | Default result formatter          |
+
+### Factory Functions
 
 | Function                            | Description                      |
 |-------------------------------------|----------------------------------|
@@ -95,15 +141,57 @@ const result = chain(ok('42'), parse) // ok(42)
 | `createFormDirtyGuard(options)`     | Navigation guard for dirty forms |
 | `createSessionPersistence(options)` | Session storage adapter          |
 
+### Error Handling
+
+| Export                 | Description                        |
+|------------------------|------------------------------------|
+| `EcosystemError`       | Base error class for all packages  |
+| `isEcosystemError(e)`  | Type guard for ecosystem errors    |
+
 ### Shared Types
 
-| Type                         | Description                     |
-|------------------------------|---------------------------------|
-| `Result<T, E>`               | Success or failure union        |
-| `Unsubscribe`                | Cleanup function type           |
-| `EmbeddingAdapterInterface`  | Embedding generation contract   |
-| `ToolFormatAdapterInterface` | Tool format conversion          |
-| `BuiltContext`               | Assembled context for inference |
+| Type                                      | Description                           |
+|-------------------------------------------|---------------------------------------|
+| `Result<T, E>`                            | Success or failure union              |
+| `Ok<T>`, `Err<E>`                         | Result discriminants                  |
+| `Unsubscribe`                             | Cleanup function type                 |
+| `DestroyFn`                               | Resource cleanup function             |
+| `SubscriptionToHook<T>`                   | Convert subscriptions to hooks        |
+| `Embedding`                               | Float32Array embedding vector         |
+| `ToolCall`, `ToolResult`, `ToolSchema`    | Tool-related types                    |
+| `ScoredResult`                            | Search result with score              |
+| `ContextFrame`, `BuiltContext`            | Context management types              |
+| `TokenBudgetState`, `TokenBudgetLevel`    | Token budget types                    |
+
+### Adapter Interfaces
+
+| Interface                                 | Category      | Description                    |
+|-------------------------------------------|---------------|--------------------------------|
+| `EmbeddingAdapterInterface`               | Source        | Embedding generation           |
+| `ToolFormatAdapterInterface`              | Transform     | Provider tool formatting       |
+| `SimilarityAdapterInterface`              | Transform     | Vector similarity computation  |
+| `DeduplicationAdapterInterface`           | Transform     | Frame deduplication            |
+| `TruncationAdapterInterface`              | Transform     | Context truncation             |
+| `PriorityAdapterInterface`                | Transform     | Frame priority ordering        |
+| `RetryAdapterInterface`                   | Policy        | Retry behavior                 |
+| `RateLimitAdapterInterface`               | Policy        | Rate limiting                  |
+| `EmbeddingCacheAdapterInterface`          | Enhancement   | Embedding caching              |
+| `BatchAdapterInterface`                   | Enhancement   | Batch processing               |
+| `RerankerAdapterInterface`                | Enhancement   | Result reranking               |
+| `VectorStorePersistenceAdapterInterface`  | Persistence   | Vector storage                 |
+
+### Minimal Cross-Package Interfaces
+
+| Interface                   | Description                          |
+|-----------------------------|--------------------------------------|
+| `MinimalDatabaseAccess<T>`  | IndexedDB access without dependency  |
+| `MinimalStoreAccess<T>`     | Store operations interface           |
+| `MinimalDirectoryAccess`    | OPFS directory access                |
+| `MinimalFileAccess`         | OPFS file access                     |
+| `ToolRegistryMinimal`       | Tool registry without dependency     |
+| `VectorStoreMinimal<T>`     | Vector store without dependency      |
+| `FormMinimal<T>`            | Form state without dependency        |
+| `SerializableSession`       | Session serialization interface      |
 
 ---
 
@@ -112,7 +200,7 @@ const result = chain(ok('42'), parse) // ok(42)
 ### Result Pattern
 
 ```ts
-import { ok, err, isOk, unwrap } from '@mikesaintsg/core'
+import { ok, err, isOk, unwrap, map, chain } from '@mikesaintsg/core'
 
 function divide(a: number, b: number) {
   if (b === 0) return err('DIVISION_BY_ZERO')
@@ -121,52 +209,109 @@ function divide(a: number, b: number) {
 
 const result = divide(10, 2)
 const value = unwrap(result, 0) // 5
+
+// Chain operations
+const doubled = chain(divide(10, 2), n => ok(n * 2)) // ok(10)
 ```
 
-### Tool Call Bridge
+### Custom Error Class
 
 ```ts
-import { createToolCallBridge } from '@mikesaintsg/core'
+import { EcosystemError, isEcosystemError } from '@mikesaintsg/core'
 
-const bridge = createToolCallBridge({
-  registry,
-  timeout: 30000,
-  onError: (error, toolCall) => console.error(error),
+type StorageErrorCode = 'NOT_FOUND' | 'QUOTA_EXCEEDED' | 'WRITE_FAILED'
+
+class StorageError extends EcosystemError {
+  readonly code: StorageErrorCode
+
+  constructor(code: StorageErrorCode, message: string, cause?: Error) {
+    super(message, cause)
+    this.code = code
+  }
+}
+
+try {
+  throw new StorageError('NOT_FOUND', 'Document not found')
+} catch (error) {
+  if (isEcosystemError(error)) {
+    console.log(error.code) // 'NOT_FOUND'
+  }
+}
+```
+
+### Retrieval Tool
+
+```ts
+import { createRetrievalTool } from '@mikesaintsg/core'
+
+const { schema, handler } = createRetrievalTool({
+  vectorStore,
+  name: 'search_docs',
+  description: 'Search documentation for relevant information',
+  defaultLimit: 5,
+  scoreThreshold: 0.7,
 })
 
-const result = await bridge.execute(toolCall)
+// Register with tool registry
+registry.register(schema, handler)
 ```
 
-### With TypeScript
+### Session Persistence
 
 ```ts
-import type { 
-  EmbeddingAdapterInterface, 
-  Result 
-} from '@mikesaintsg/core'
+import { createSessionPersistence } from '@mikesaintsg/core'
 
-// Type-safe adapter interface
-const adapter: EmbeddingAdapterInterface = createAdapter()
+const persistence = createSessionPersistence({
+  database,
+  storeName: 'chat_sessions',
+  autoprune: 7 * 24 * 60 * 60 * 1000, // 7 days
+})
 
-// Inferred result types
-function safeParse(input: string): Result<number, 'PARSE_ERROR'> {
-  const n = parseInt(input, 10)
-  return isNaN(n) ? err('PARSE_ERROR') : ok(n)
-}
+await persistence.save('session-1', session)
+const loaded = await persistence.load('session-1')
 ```
 
+### Form Dirty Guard
+
+```ts
+import { createFormDirtyGuard } from '@mikesaintsg/core'
+
+const guard = createFormDirtyGuard({
+  form,
+  confirmFn: (message) => window.confirm(message),
+  message: 'You have unsaved changes. Continue?',
+  excludePages: ['logout'],
+})
+
+router.beforeNavigate(guard)
+```
+
+---
+
+## Constants
+
+| Constant                     | Value  | Description                    |
+|------------------------------|--------|--------------------------------|
+| `BRIDGE_DEFAULT_TIMEOUT`     | 30000  | Default bridge timeout (ms)    |
+| `RETRIEVAL_DEFAULT_LIMIT`    | 10     | Default retrieval result limit |
+| `RETRIEVAL_MAX_LIMIT`        | 100    | Maximum retrieval result limit |
+| `FORM_DIRTY_DEFAULT_MESSAGE` | string | Default form guard message     |
+
 ---
 
 ## Ecosystem Integration
 
 | Package                        | Integration                                    |
 |--------------------------------|------------------------------------------------|
-| `@mikesaintsg/adapters`        | Provider and embedding adapter implementations |
+| `@mikesaintsg/adapters`        | Implements adapter interfaces                  |
 | `@mikesaintsg/inference`       | Uses shared types and bridge functions         |
 | `@mikesaintsg/vectorstore`     | Uses embedding and persistence interfaces      |
 | `@mikesaintsg/contextprotocol` | Uses tool types and registry interface         |
+| `@mikesaintsg/contextbuilder`  | Uses context frame and budget types            |
+| `@mikesaintsg/indexeddb`       | Implements MinimalDatabaseAccess               |
+| `@mikesaintsg/filesystem`      | Implements MinimalDirectoryAccess              |
 
-See [Integration Patterns](./guides/core.md#integration-patterns) for details.
+See [Integration Guide](./guides/integration.md) for detailed patterns.
 
 ---