Shared: Shared Types and Utilities

The Problem

Multi-package ecosystems need consistent type definitions. Type mismatches between packages cause silent runtime errors. No standard error handling pattern leads to inconsistent failure modes.

When packages define their own types independently, subtle incompatibilities emerge at integration boundaries. A "Share" type in one package may differ from the "Share" type in another by a single field, causing silent data loss or corruption at runtime despite successful TypeScript compilation.

Without a standard error handling pattern, some packages throw exceptions, others return null, and still others use custom error objects. Callers cannot predict failure modes, leading to unhandled errors in production and inconsistent user experiences across the platform.

The Old Way

The PRIVATE.ME Solution

A single source of truth for every type, constant, and error pattern in the PRIVATE.ME ecosystem. Result<T,E> discriminated unions enforce exhaustive error handling at compile time.

All 65 packages in the ecosystem import their shared types from @private.me/shared. When a type changes, it changes everywhere simultaneously. No drift, no mismatches, no silent incompatibilities. TypeScript strict mode catches any integration issues at compile time, not runtime.

The Result<T,E> pattern replaces thrown exceptions with discriminated unions. Every function returns either { ok: true, value: T } or { ok: false, error: E }. Callers must handle both cases. The compiler enforces this. Unhandled errors become impossible.

The New Way

How It Works

The shared package provides three layers: type definitions (interfaces and enums), utility constructors (ok/err/uuid), and domain constants (TLV codes, magic numbers, thresholds).

Use Cases

Integration

import { ok, err, type Result } from '@private.me/shared';

// Type-safe error handling
function processShare(data: Uint8Array): Result<Share, ShareError> {
  if (data.length === 0) {
    return err({ code: 'EMPTY_DATA', message: 'No data' });
  }
  return ok({ index: 0, data, hmac: computeHmac(data) });
}

// Caller MUST handle both cases
const result = processShare(input);
if (result.ok) {
  console.log(result.value); // Share
} else {
  console.log(result.error); // ShareError
}

Security Properties

Ship Proofs, Not Source

Shared generates cryptographic proofs of correct execution without exposing proprietary algorithms. Verify integrity using zero-knowledge proofs — no source code required.

Use Cases