@relational-fabric/canon 1.0.0

package/src/registry.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Tests for canon registry
+ */
+
+import type { CanonConfig } from './types/index.js'
+import { describe, expect, it } from 'vitest'
+import { createRegistry, Registry } from './registry.js'
+
+// Declare test canons in the type system
+declare module './types/canons.js' {
+  interface Canons {
+    TestCanon: {
+      Id: {
+        $basis: { id: string }
+      }
+    }
+    Canon1: Record<string, never>
+  }
+}
+
+// Test canon configurations
+const testCanonConfig: CanonConfig = {
+  axioms: {
+    Id: {
+      $basis: (v: unknown): v is { id: string } => true,
+      key: 'id',
+    },
+  },
+}
+
+const emptyCanonConfig: CanonConfig = {
+  axioms: {},
+}
+
+describe('registry', () => {
+  describe('register', () => {
+    it('should register a canon', () => {
+      const registry = new Registry()
+
+      registry.register('TestCanon', testCanonConfig)
+
+      expect(registry.has('TestCanon')).toBe(true)
+      expect(registry.get('TestCanon')).toBe(testCanonConfig)
+    })
+  })
+
+  describe('size', () => {
+    it('should return number of registered canons', () => {
+      const registry = new Registry()
+      expect(registry.size).toBe(0)
+
+      registry.register('Canon1', emptyCanonConfig)
+      expect(registry.size).toBe(1)
+    })
+  })
+
+  describe('clear', () => {
+    it('should remove all canons', () => {
+      const registry = new Registry()
+      registry.register('Canon1', emptyCanonConfig)
+      expect(registry.size).toBe(1)
+
+      registry.clear()
+      expect(registry.size).toBe(0)
+    })
+  })
+})
+
+describe('createRegistry', () => {
+  it('should create an empty registry', () => {
+    const registry = createRegistry()
+    expect(registry).toBeInstanceOf(Registry)
+    expect(registry.size).toBe(0)
+  })
+})

package/src/registry.ts

@@ -0,0 +1,72 @@
+/**
+ * Canon Registry
+ *
+ * Class for storing and managing canon configurations.
+ */
+
+import type { CanonConfig, Canons } from './types/index.js'
+
+/**
+ * Canon Registry class
+ *
+ * Stores canon configurations. Axioms are defined within canons.
+ */
+export class Registry {
+  private canons = new Map<string, CanonConfig>()
+
+  /**
+   * Register a canon
+   */
+  register<Label extends keyof Canons>(label: Label, config: CanonConfig): void {
+    this.canons.set(label as string, config)
+  }
+
+  /**
+   * Get a canon configuration by label
+   */
+  get(label: string): CanonConfig | undefined {
+    return this.canons.get(label)
+  }
+
+  /**
+   * Get all registered canon configurations
+   */
+  values(): IterableIterator<CanonConfig> {
+    return this.canons.values()
+  }
+
+  /**
+   * Make registry iterable - iterates over canon configs
+   */
+  *[Symbol.iterator](): Iterator<CanonConfig> {
+    yield * this.canons.values()
+  }
+
+  /**
+   * Check if a canon is registered
+   */
+  has(label: string): boolean {
+    return this.canons.has(label)
+  }
+
+  /**
+   * Get the number of registered canons
+   */
+  get size(): number {
+    return this.canons.size
+  }
+
+  /**
+   * Clear all registered canons
+   */
+  clear(): void {
+    this.canons.clear()
+  }
+}
+
+/**
+ * Create a new empty registry
+ */
+export function createRegistry(): Registry {
+  return new Registry()
+}

package/src/shell.test.ts

@@ -0,0 +1,63 @@
+/**
+ * Tests for global shell
+ */
+
+import type { CanonConfig } from './types/index.js'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { Registry } from './registry.js'
+import { declareCanon, getRegistry, resetRegistry } from './shell.js'
+
+describe('shell', () => {
+  beforeEach(() => {
+    resetRegistry()
+  })
+
+  afterEach(() => {
+    // Just clear - isolated tests don't need full restoration
+    resetRegistry()
+  })
+
+  describe('getRegistry', () => {
+    it('should return the global registry', () => {
+      const registry = getRegistry()
+      expect(registry).toBeInstanceOf(Registry)
+    })
+  })
+
+  describe('resetRegistry', () => {
+    it('should clear the global registry', () => {
+      const config: CanonConfig = {
+        axioms: {
+          Id: {
+            $basis: (v: unknown): v is { id: string } => true,
+            key: 'id',
+          },
+        },
+      }
+
+      declareCanon('TestCanon' as any, config)
+      expect(getRegistry().size).toBe(1)
+
+      resetRegistry()
+      expect(getRegistry().size).toBe(0)
+    })
+  })
+
+  describe('declareCanon', () => {
+    it('should register canon in global registry', () => {
+      const config: CanonConfig = {
+        axioms: {
+          Id: {
+            $basis: (v: unknown): v is { id: string } => true,
+            key: 'id',
+          },
+        },
+      }
+
+      declareCanon('TestCanon' as any, config)
+
+      expect(getRegistry().has('TestCanon')).toBe(true)
+      expect(getRegistry().get('TestCanon')).toBe(config)
+    })
+  })
+})

package/src/shell.ts

@@ -0,0 +1,49 @@
+/**
+ * Canon Shell
+ *
+ * Singleton registry instance with convenience API.
+ */
+
+import type { CanonConfig, Canons } from './types/index.js'
+import { createRegistry, type Registry } from './registry.js'
+import { defineCanon } from './types/index.js'
+
+/**
+ * Global singleton registry
+ */
+const globalRegistry: Registry = createRegistry()
+
+/**
+ * Get the current global registry
+ */
+export function getRegistry(): Registry {
+  return globalRegistry
+}
+
+/**
+ * Reset the global registry to empty
+ */
+export function resetRegistry(): void {
+  globalRegistry.clear()
+}
+
+/**
+ * Declare a canon in the global registry
+ *
+ * @param label - The canon label
+ * @param config - The canon configuration
+ */
+export function declareCanon<Label extends keyof Canons>(label: Label, config: CanonConfig): void {
+  globalRegistry.register(label, defineCanon(config))
+}
+
+/**
+ * Register multiple canons at once (for module-style registration)
+ *
+ * @param canons - Object mapping canon labels to their configurations
+ */
+export function registerCanons(canons: Record<string, CanonConfig>): void {
+  for (const [label, config] of Object.entries(canons)) {
+    globalRegistry.register(label as keyof Canons, defineCanon(config))
+  }
+}

package/src/testing.ts

@@ -0,0 +1,43 @@
+/**
+ * Compile-time type testing utilities for Canon
+ */
+
+/**
+ * Expect the first type to extend the second type.
+ */
+export type Expect<A, B> = A extends B ? true : false
+
+/**
+ * Assert that a type resolves to `true`.
+ */
+export type IsTrue<A> = Expect<A, true>
+
+/**
+ * Assert that a type resolves to `false`.
+ */
+export type IsFalse<A> = A extends false ? true : false
+
+/**
+ * Runtime no-op function that enforces the provided type resolves to `true`.
+ */
+export function invariant<_ extends true>(): void {
+  // Intentionally empty – the generic constraint encodes the assertion.
+}
+
+// ---------------------------------------------------------------------------
+// Self-validation of the utilities
+// ---------------------------------------------------------------------------
+
+void invariant<Expect<true, true>>()
+void invariant<Expect<'value', string>>()
+void invariant<Expect<1 | 2, number>>()
+void invariant<IsFalse<Expect<string, number>>>()
+
+// @ts-expect-error - Expect should fail when the left side does not extend the right.
+void invariant<Expect<{ id: string }, { id: number }>>()
+
+// @ts-expect-error - IsTrue rejects non-true values.
+void invariant<IsTrue<false>>()
+
+// @ts-expect-error - IsFalse only accepts precisely `false`.
+void invariant<IsFalse<true>>()

package/src/types/axioms.ts

@@ -0,0 +1,131 @@
+/**
+ * Axiom type system for Canon
+ *
+ * Axioms are atomic building blocks that define semantic concepts
+ * (like ID, type, version) that can be found in different data structures.
+ */
+
+import type { TypeGuard } from './guards.js'
+import { type Expect, invariant } from '../testing.js'
+
+/**
+ * Base axiom type that merges configuration with metadata
+ *
+ * @template TConfig - The axiom configuration shape
+ * @template TMeta - The metadata shape
+ */
+export type Axiom<TConfig, TMeta> = TConfig & { $meta: TMeta }
+
+/**
+ * Key-name axiom pattern for field-name-based concepts
+ *
+ * This represents concepts that can be found by looking for a specific
+ * key name within an object (e.g., 'id', '@id', '_id').
+ */
+export type KeyNameAxiom = Axiom<
+  {
+    $basis: Record<string, unknown>
+    key: string
+  },
+  {
+    [key: string]: unknown
+  }
+>
+
+/**
+ * Representation axiom for data with multiple representations
+ *
+ * This represents concepts that can be converted between different formats
+ * with a canonical representation (e.g., timestamps, references).
+ *
+ * @template T - The input type that can be converted
+ * @template C - The canonical type (defaults to unknown)
+ */
+export type RepresentationAxiom<T, C = unknown> = Axiom<
+  {
+    $basis: T | TypeGuard<unknown>
+    isCanonical: (value: unknown) => value is C
+  },
+  {
+    [key: string]: unknown
+  }
+>
+
+/**
+ * Global registry of axioms available in Canon
+ *
+ * This interface is meant to be augmented by axiom implementers.
+ * Each axiom represents a semantic concept that might vary in shape
+ * between codebases but is otherwise equivalent.
+ *
+ * @example
+ * ```typescript
+ * declare module '@relational-fabric/canon' {
+ *   interface Axioms {
+ *     Id: KeyNameAxiom
+ *     Type: KeyNameAxiom
+ *   }
+ * }
+ * ```
+ */
+export interface Axioms {}
+
+/**
+ * Canonical reference type for entity relationships
+ *
+ * @template R - The reference type (usually string)
+ * @template T - The value type (defaults to unknown)
+ */
+export interface EntityReference<R, T = unknown> {
+  ref: R
+  value?: T
+  resolved: boolean
+}
+
+/**
+ * Extract the value type from an axiom's $basis field
+ *
+ * @template TLabel - The axiom label (e.g., 'Id', 'Type')
+ */
+export type AxiomValue<TLabel extends keyof Axioms> = Axioms[TLabel] extends {
+  $basis: infer TBasis
+}
+  ? TBasis extends TypeGuard<infer T>
+    ? T
+    : TBasis
+  : never
+
+/**
+ * Runtime configuration for an axiom
+ *
+ * This represents the actual runtime behavior including type guards
+ * and metadata values.
+ */
+export interface AxiomConfig {
+  $basis: TypeGuard<unknown>
+  [key: string]: unknown
+}
+
+/**
+ * Define an axiom runtime configuration
+ *
+ * Simply returns the config unchanged - useful for creating exportable axioms.
+ *
+ * @param config - The runtime axiom configuration
+ * @returns The same config object
+ */
+export function defineAxiom(config: AxiomConfig): AxiomConfig {
+  return config
+}
+
+// ---------------------------------------------------------------------------
+// Compile-time invariants
+// ---------------------------------------------------------------------------
+
+void invariant<Expect<KeyNameAxiom['key'], string>>()
+void invariant<
+  Expect<RepresentationAxiom<string, string>['isCanonical'], (value: unknown) => value is string>
+>()
+void invariant<Expect<EntityReference<string>['ref'], string>>()
+void invariant<Expect<EntityReference<string>['resolved'], boolean>>()
+void invariant<Expect<AxiomConfig['$basis'], TypeGuard<unknown>>>()

package/src/types/canons.ts

@@ -0,0 +1,78 @@
+/**
+ * Canon type system
+ *
+ * Canons are universal type blueprints that implement axioms for specific
+ * data formats. Multiple canons can exist simultaneously, each representing
+ * different formats.
+ */
+
+import type { AxiomConfig, Axioms } from './axioms.js'
+import { type Expect, invariant } from '../testing.js'
+
+/**
+ * Canon type that maps axiom labels to their type-level configurations
+ *
+ * @template TAxioms - Object mapping axiom labels to their configurations
+ */
+export type Canon<TAxioms extends Partial<Axioms>> = TAxioms
+
+/**
+ * Global registry of canons available in Canon
+ *
+ * This interface is meant to be augmented by canon implementers.
+ *
+ * @example
+ * ```typescript
+ * declare module '@relational-fabric/canon' {
+ *   interface Canons {
+ *     Internal: InternalCanon
+ *     JsonLd: JsonLdCanon
+ *   }
+ * }
+ * ```
+ */
+export interface Canons {}
+
+/**
+ * Runtime configuration for a canon
+ *
+ * Maps axiom labels to their runtime configurations including type guards.
+ */
+export interface CanonConfig {
+  axioms: Record<string, AxiomConfig>
+}
+
+/**
+ * Constraint type ensuring a value satisfies an axiom's requirements
+ *
+ * @template TAxiomLabel - The axiom label (e.g., 'Id', 'Type')
+ * @template TCanonLabel - Optional specific canon to check against
+ */
+export type Satisfies<
+  TAxiomLabel extends keyof Axioms,
+  TCanonLabel extends keyof Canons = keyof Canons,
+> = {
+  [K in keyof Canons]: TAxiomLabel extends keyof Canons[K]
+    ? Canons[K][TAxiomLabel] extends { $basis: infer TBasis }
+      ? TBasis
+      : never
+    : never
+}[TCanonLabel]
+
+/**
+ * Define a canon runtime configuration (for module-style exports)
+ *
+ * Simply returns the config unchanged - useful for creating exportable canons.
+ *
+ * @param config - The runtime canon configuration
+ * @returns The same config object
+ */
+export function defineCanon(config: CanonConfig): CanonConfig {
+  return config
+}
+
+// ---------------------------------------------------------------------------
+// Compile-time invariants
+// ---------------------------------------------------------------------------
+
+void invariant<Expect<CanonConfig['axioms'], Record<string, AxiomConfig>>>()

package/src/types/guards.ts

@@ -0,0 +1,51 @@
+/**
+ * Type guard utilities for Canon type system
+ */
+
+import { type Expect, invariant } from '../testing.js'
+
+/**
+ * Type guard pattern that preserves specific types when narrowing
+ *
+ * CRITICAL: The parameter type must be `T | unknown` (NOT just `unknown`).
+ *
+ * While `T | unknown` reduces to `unknown` at runtime (since unknown is the
+ * top type), the explicit union is essential for TypeScript's type narrowing.
+ * Using just `unknown` makes T disjoint from the parameter, breaking type
+ * discrimination. The union ensures T is NOT disjoint with the parameter type.
+ *
+ * This interface uses overloads to properly discriminate the target type
+ * from unknown, allowing TypeScript to infer the most specific type.
+ */
+export interface TypeGuard<T> {
+  <U extends T>(obj: U | unknown): obj is U
+  (obj: T | unknown): obj is T
+}
+
+/**
+ * Predicate function type - a boolean-returning function
+ *
+ * This is the input to typeGuard(), which converts it to a TypeGuard.
+ * CRITICAL: Must use `T | unknown` to maintain type compatibility.
+ */
+export interface Predicate<T> {
+  (obj: T | unknown): boolean
+  <U extends T>(obj: U | unknown): boolean
+}
+
+// ---------------------------------------------------------------------------
+// Compile-time invariants
+// ---------------------------------------------------------------------------
+
+type ExampleGuard = TypeGuard<{ id: string }>
+type ExamplePredicate = Predicate<{ id: string }>
+
+type GuardTarget<T> = T extends TypeGuard<infer Target> ? Target : never
+type PredicateTarget<T> = T extends Predicate<infer Target> ? Target : never
+type GuardReturn<T> = T extends (value: unknown) => value is infer R ? R : never
+type PredicateReturn<T> = T extends (value: unknown) => infer R ? R : never
+
+void invariant<Expect<GuardTarget<ExampleGuard>, { id: string }>>()
+void invariant<Expect<PredicateTarget<ExamplePredicate>, { id: string }>>()
+void invariant<Expect<GuardReturn<ExampleGuard>, { id: string }>>()
+void invariant<Expect<PredicateReturn<ExamplePredicate>, boolean>>()

package/src/types/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Canon type system exports
+ */
+
+export * from './axioms.js'
+export * from './canons.js'
+export * from './guards.js'
+export * from './js.js'
+export * from './objects.js'
+export * from './radar.js'

package/src/types/js.ts

@@ -0,0 +1,25 @@
+import { type Expect, invariant } from '../testing.js'
+
+export interface JsType {
+  string: string
+  number: number
+  boolean: boolean
+  object: object
+  array: unknown[]
+  null: null
+  undefined: undefined
+  symbol: symbol
+  bigint: bigint
+  // @eslint-disable-next-line @typescript-eslint/no-explicit-any
+  function: (...args: any[]) => any // This is the only time we're allowing any
+}
+
+export type JsTypeName = keyof JsType
+
+// ---------------------------------------------------------------------------
+// Compile-time invariants
+// ---------------------------------------------------------------------------
+
+void invariant<Expect<JsType['string'], string>>()
+void invariant<Expect<JsType['array'], unknown[]>>()
+void invariant<Expect<JsTypeName, keyof JsType>>()

package/src/types/objects.ts

@@ -0,0 +1,32 @@
+/**
+ * Object type definitions for Canon
+ */
+
+import { type Expect, invariant } from '../testing.js'
+
+/**
+ * Plain old JavaScript object type
+ */
+export type Pojo = Record<string, unknown>
+
+/**
+ * Pojo with a specific property of a given type
+ *
+ * @template T - The base Pojo type
+ * @template K - The key name
+ * @template V - The value type
+ */
+export type PojoWith<T extends Pojo, K extends string, V = unknown> = T & { [P in K]: V }
+
+// ---------------------------------------------------------------------------
+// Compile-time invariants
+// ---------------------------------------------------------------------------
+
+interface SampleBase extends Pojo {
+  name: string
+}
+type SamplePojo = PojoWith<SampleBase, 'id', string>
+
+void invariant<Expect<Pojo, Record<string, unknown>>>()
+void invariant<Expect<SamplePojo['id'], string>>()
+void invariant<Expect<SamplePojo['name'], string>>()