@relational-fabric/canon 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Relational Fabric
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,329 @@
+---
+layout: home
+
+hero:
+  name: '@relational-fabric/canon'
+  text: 'Universal Type Primitives & Axiomatic Systems'
+  tagline: 'Build robust, data-centric applications with consistent type blueprints and a curated library ecosystem'
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /docs/
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/RelationalFabric/canon
+
+features:
+  - icon: 🔄
+    title: Lazy Typing Pattern
+    details: Write type-safe code against semantic concepts while deferring specific implementations through axioms, canons, and universal APIs
+  - icon: 🧩
+    title: Axioms
+    details: Define semantic concepts independent of data shape - the "what" of your type system
+  - icon: 📐
+    title: Canons
+    details: Provide shape-specific implementations of axioms - the "how" for each data source
+  - icon: 🛠️
+    title: Universal APIs
+    details: Functions that work across all canons - the "interface" for your application code
+  - icon: 🎯
+    title: Universal Type Primitives
+    details: Battle-tested types from the TypeScript ecosystem providing a solid foundation for data-centric applications
+  - icon: 📚
+    title: Curated Library Ecosystem
+    details: Known good set of libraries and modules as a canonical starting point for your projects
+  - icon: 🏗️
+    title: Modern TypeScript
+    details: Based on Node.js 22+ with latest TypeScript features, ES modules, and comprehensive tooling
+  - icon: 📖
+    title: Architecture Decisions
+    details: Documented ADRs and transparent technology radar for strategic planning
+---
+
+**Canon** solves the "empty room problem" by providing universal type primitives and axiomatic systems for building robust, data-centric applications. Instead of starting from scratch with each new project, Canon offers consistent design decisions and type blueprints that can be shared across projects and data shapes.
+
+## What is Canon?
+
+Canon is a modern TypeScript package that enables **lazy typing** - writing type-safe code against semantic concepts while deferring specific implementations to runtime configuration. This is achieved through three complementary parts:
+
+### The Lazy Typing Triplet
+
+#### 1. Axioms - Define Semantic Concepts
+
+Axioms define **what** semantic concepts mean, independent of any specific data shape:
+
+- Define the semantic concept (e.g., "unique identifier", "type classification", "temporal data")
+- Specify the type structure without implementation details
+- Enable compile-time type safety through TypeScript interfaces
+
+#### 2. Canons - Implement for Shapes
+
+Canons provide **how** each axiom is implemented for specific data shapes:
+
+- Provide shape-specific field names and structures
+- Multiple canons can coexist for different data sources
+- Register both type-level and runtime configurations
+
+#### 3. Universal APIs - Work Across Shapes
+
+Universal APIs provide **the interface** your application code uses:
+
+- Single API that works across all registered canons
+- Type-safe functions that adapt to different data shapes
+- No shape-specific code in your business logic
+
+### Additional Capabilities
+
+#### Universal Type Primitives
+
+- Battle-tested types from the TypeScript ecosystem
+- Foundation for building data-centric applications
+- Type-safe operations and proven patterns
+
+#### Type Testing Utilities
+
+- Zero-runtime-cost compile-time type assertions
+- Guard against type regressions with `Expect<A, B>`
+- Document type expectations directly in code
+- Positive and negative type checks with `IsTrue` and `IsFalse`
+
+#### Curated Library Ecosystem
+
+Canon serves as a **canonical starting point** by providing:
+
+- **Pre-configured TypeScript setup** - Base configurations that work out of the box
+- **Curated dependency set** - Known good versions of essential libraries for common needs
+- **Standardized patterns** - Consistent approaches to common problems
+- **Best practice implementations** - Proven solutions for type safety and data handling
+- **Sensible defaults** - Recommended choices when selecting data structures
+
+This approach reduces decision fatigue and provides confidence in your technology stack while recognizing that in many real-world scenarios you must work with existing data structures.
+
+## Quick Start
+
+### Install
+
+```bash
+npm install @relational-fabric/canon
+```
+
+### Use TypeScript Configuration
+
+```json
+{
+  "extends": "@relational-fabric/canon/tsconfig"
+}
+```
+
+### Use ESLint Configuration
+
+```javascript
+// eslint.config.js
+import createEslintConfig from '@relational-fabric/canon/eslint'
+
+export default createEslintConfig()
+```
+
+#### Providing Custom Options
+
+```javascript
+// eslint.config.js
+import createEslintConfig from '@relational-fabric/canon/eslint'
+
+export default createEslintConfig({
+  ignores: ['custom-ignore'],
+  rules: {
+    'no-console': 'warn',
+  },
+})
+```
+
+## Requirements
+
+This package requires the following peer dependencies:
+
+- **Node.js**: 22.0.0 or higher
+- **TypeScript**: 5.0.0 or higher
+- **ESLint**: 9.0.0 or higher
+
+## Core Concepts
+
+### The Lazy Typing Pattern
+
+Canon implements **lazy typing** through three complementary components that work together:
+
+#### Axioms
+
+Axioms define semantic concepts independent of data shape. They specify **what** concepts your code works with, such as:
+
+- Unique identifiers across different systems
+- Type information and classification
+- Versioning and change tracking
+- Temporal data with conversion between representations
+- Relationships between entities
+
+See [docs/axioms.md](docs/axioms.md) for the complete type system architecture.
+
+#### Canons
+
+Canons provide shape-specific implementations of axioms. They specify **how** each semantic concept is represented in a particular data shape:
+
+- **Declarative Style**: Local configurations for specific use cases
+- **Module Style**: Shareable configurations across projects
+- **Type Safety**: Full TypeScript support with compile-time checking
+- **Multiple Shapes**: Each canon handles one data shape's implementation
+
+See [docs/canons.md](docs/canons.md) for implementation patterns.
+
+#### Universal APIs
+
+Universal APIs provide functions that work across all registered canons. They are **the interface** your application code uses:
+
+- Write code once that works with any registered canon
+- Automatic adaptation to different data shapes
+- Full type safety maintained across all shapes
+
+See [reference/api.md](reference/api.md) for available APIs.
+
+## Package Exports
+
+- **Main package**: `@relational-fabric/canon` - Core axioms and canons
+- **TypeScript config**: `@relational-fabric/canon/tsconfig` - Base TypeScript configuration
+- **ESLint config**: `@relational-fabric/canon/eslint` - ESLint configuration function
+
+## Key Patterns
+
+### Module Augmentation
+
+Register axioms and canons using TypeScript module augmentation:
+
+```typescript
+declare module '@relational-fabric/canon' {
+  interface Axioms {
+    MyAxiom: MyAxiomType
+  }
+  interface Canons {
+    MyCanon: MyCanonType
+  }
+}
+```
+
+### Naming Conventions
+
+- **Axiom Keys**: PascalCase, plural for general concepts (`Timestamps`, `References`), singular for specific concepts (`Id`, `Type`)
+- **Function Names**: Use relational `*Of` pattern (`idOf()`, `typeOf()`) not imperative `get*` patterns
+- **Type Names**: PascalCase for all type definitions
+- **Variables**: camelCase for all variables and parameters
+- **Distinguished Keys**: Use `$` prefix only for Canon's internal keys (`$basis`, `$meta`)
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for complete conventions.
+
+## Integration
+
+Canon is designed to compose with existing TypeScript libraries and provides:
+
+- **Type Safety**: Full TypeScript support with strict type checking
+- **Flexibility**: Work with existing data structures or define new ones
+- **Shape Agnostic**: Support for diverse data shapes through universal semantic interfaces
+- **Extensibility**: Add your own axioms and canons as needed
+
+## Planning and Strategy
+
+Canon maintains transparent planning and strategic direction:
+
+- **Technology Radar**: [planning/radar/](planning/radar/) - Technology recommendations and assessments
+- **Strategic Vision**: [planning/](planning/) - Long-term direction and positioning
+- **Development Roadmap**: [planning/](planning/) - Detailed development phases and milestones
+- **Architecture Decisions**: [docs/adrs/](docs/adrs/) - Documented ADRs for major decisions
+- **Update Radar**: `npm run build:radar` - Convert YAML to CSV for visualization
+
+## Development
+
+### Prerequisites
+
+- Node.js 22+
+- npm or yarn
+
+### Setup
+
+```bash
+git clone <repository-url>
+cd canon
+npm install
+```
+
+### Available Scripts
+
+**Checks (Validation):**
+
+- `npm run check:all` - Run all checks (lint, type check, and tests)
+- `npm run checks` - Alias for check:all
+- `npm run check:types` - Type check all code (src + examples)
+- `npm run check:types:src` - Type check source code only
+- `npm run check:types:examples` - Type check examples only
+- `npm run check:lint` - Lint code
+- `npm run check:lint:fix` - Fix ESLint issues automatically
+- `npm run check:radar` - Validate radar configuration
+- `npm test` - Run tests (npm standard)
+- `npm run check:test` - Run tests (includes examples)
+
+**Development:**
+
+- `npm run dev` - Run TypeScript in watch mode
+
+**Documentation:**
+
+- `npm run build:docs` - Build documentation for production
+- `npm run build:docs:restore` - Restore README.md files from build
+
+**Note**: The documentation build process uses a GitHub-first approach. All files use `README.md` naming in the repository for GitHub compatibility. During build, files are temporarily renamed to `index.md` for VitePress routing, then automatically restored. Always edit `README.md` files directly.
+
+**Architecture Decision Records:**
+
+- `cd docs/adrs && npx adr new "Title"` - Create a new ADR
+- `npm run build:adr` - Build all ADR artifacts (TOC + index)
+- `npm run build:adr:toc` - Generate table of contents
+- `npm run build:adr:index` - Generate ADR index in documentation
+
+**Technology Radar:**
+
+- `npm run build:radar` - Convert YAML radar data to CSV
+
+**Examples:**
+
+- `npm run build:docs:examples` - Generate documentation from examples
+
+## Documentation
+
+Canon provides comprehensive documentation to help you understand and use the system:
+
+### Core Documentation
+
+- **[Getting Started](docs/)** - Introduction and quick start guide
+- **[Axioms](docs/axioms.md)** - Fundamental building blocks and type system
+- **[Canons](docs/canons.md)** - Universal type blueprints and implementation patterns
+- **[Contributing](CONTRIBUTING.md)** - Conventions, naming patterns, and development workflow
+
+### Reference Documentation
+
+- **[API Reference](reference/api.md)** - Complete API documentation
+- **[Core Axioms](reference/axioms.md)** - Detailed axiom specifications
+- **[Canons Reference](reference/canons.md)** - Canon implementation guide
+- **[Type Testing Utilities](docs/type-testing/)** - Compile-time type assertions and invariants
+- **[Third-Party Integrations](reference/third-party.md)** - External library integrations
+
+### Examples
+
+- **[Deduplicating Entities](docs/examples/deduplicating-entities.md)** - Using axioms for entity deduplication
+- **[Tree Walk Over Mixed Entities](docs/examples/tree-walk-over-mixed-entities.md)** - Working with heterogeneous data structures
+- **[User Authentication Tokens](docs/examples/user-authentication-tokens.md)** - Implementing authentication patterns
+- **[More Examples](docs/examples/)** - Additional examples and use cases
+
+### Architecture
+
+- **[ADRs](docs/adrs/)** - Architecture Decision Records
+- **[Technology Radar](planning/radar/methodology.md)** - Technology assessment methodology
+
+## License
+
+MIT

package/eslint.js

@@ -0,0 +1,31 @@
+import process from 'node:process'
+import antfu from '@antfu/eslint-config'
+import { defu } from 'defu'
+
+/**
+ * Create an ESLint configuration using antfu's config with optional custom overrides
+ * @param {object} [options] - Optional configuration to merge with the default antfu config
+ * @returns {object} ESLint configuration object
+ */
+export default function createEslintConfig(options = {}, ...configs) {
+  const defaultConfig = {
+    typescript: true,
+    node: true,
+    stylistic: true, // Use ESLint Stylistic for formatting instead of Prettier
+    ignores: ['dist', 'node_modules'],
+  }
+
+  const mergedConfig = defu(options, defaultConfig)
+
+  return antfu(
+    mergedConfig,
+    {
+      rules: {
+        'no-console': process.env.CI ? 'off' : 'warn',
+        'node/prefer-global/process': 'off',
+        'style/brace-style': ['error', '1tbs', { allowSingleLine: true }],
+      },
+    },
+    ...configs,
+  )
+}

package/package.json

@@ -0,0 +1,126 @@
+{
+  "name": "@relational-fabric/canon",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "A modern TypeScript package template with ESLint and TypeScript configurations for starting new projects",
+  "author": "Relational Fabric",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/RelationalFabric/canon.git"
+  },
+  "keywords": [
+    "typescript",
+    "eslint",
+    "template",
+    "starter",
+    "configuration",
+    "package",
+    "node",
+    "lts"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./radar": {
+      "types": "./src/radar/index.ts",
+      "import": "./src/radar/index.ts"
+    },
+    "./tsconfig": "./tsconfig.base.json",
+    "./eslint": "./eslint.js"
+  },
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "bin": {
+    "adr": "./scripts/adr.js"
+  },
+  "files": [
+    "eslint.js",
+    "src",
+    "tsconfig.base.json"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build:adr": "npm-run-all build:adr:toc build:adr:index",
+    "build:adr:index": "node scripts/generate-adr-index.js",
+    "build:adr:toc": "cd docs/adrs && npx adr generate toc",
+    "build:docs": "npm run build:docs:examples && scripts/rename-readmes-for-build.sh && npx vitepress build && scripts/restore-readmes-from-build.sh",
+    "build:docs:examples": "tsx scripts/generate-examples-docs.ts",
+    "build:docs:restore": "scripts/restore-readmes-from-build.sh",
+    "build:radar": "tsx scripts/convert-radar.ts",
+    "check:all": "npm-run-all check:lint check:types check:test check:radar ",
+    "check:all:fix": "npm-run-all check:lint:fix check:types check:test",
+    "check:lint": "eslint .",
+    "check:lint:fix": "eslint . --fix",
+    "check:radar": "tsx scripts/validate-radar.ts",
+    "check:test": "vitest run",
+    "check:test:json": "vitest run --reporter=default --reporter=json --outputFile=.scratch/vitest-report.json",
+    "check:test:coverage": "vitest run --coverage",
+    "check:test:watch": "vitest run --watch",
+    "check:test:ui": "vitest run --ui",
+    "check:types": "npm run check:types:all",
+    "check:types:all": "npm-run-all check:types:src check:types:examples",
+    "check:types:examples": "tsc --noEmit --project examples/tsconfig.json",
+    "check:types:src": "tsc --noEmit",
+    "checks": "npm run check:all",
+    "dev": "tsx --watch src/index.ts",
+    "test": "npm run check:test",
+    "prepare": "husky",
+    "postinstall": "husky"
+  },
+  "peerDependencies": {
+    "eslint": "^9.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "eslint": {
+      "optional": false
+    },
+    "typescript": {
+      "optional": false
+    }
+  },
+  "dependencies": {
+    "@antfu/eslint-config": "^3.0.0",
+    "@tsconfig/node-lts": "^20.0.0",
+    "yaml": "^2.4.1"
+  },
+  "optionalDependencies": {
+    "defu": "^6.1.4"
+  },
+  "devDependencies": {
+    "@types/mdast": "^4.0.4",
+    "@types/node": "^24.7.1",
+    "@vitest/coverage-v8": "^3.2.4",
+    "adr-tools": "^2.0.4",
+    "chokidar-cli": "^3.0.0",
+    "dedent": "^1.7.0",
+    "depcheck": "^1.4.7",
+    "eslint": "^9.10.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.6",
+    "npm-run-all": "^4.1.5",
+    "remark": "^15.0.1",
+    "remark-parse": "^11.0.0",
+    "remark-stringify": "^11.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0",
+    "unified": "^11.0.5",
+    "vitepress": "^1.0.0",
+    "vitest": "^3.2.4"
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "lint-staged"
+    }
+  },
+  "lint-staged": {
+    "*.{js,jsx,ts,tsx,json,css,md}": [
+      "npx eslint --fix"
+    ]
+  }
+}

package/src/axiom.ts

@@ -0,0 +1,34 @@
+/**
+ * Axiom API functions
+ */
+
+import type { AxiomConfig, Axioms } from './types/index.js'
+import { inferCanon } from './canon.js'
+
+/**
+ * Infer axiom configuration for a value
+ *
+ * Finds the canon that matches the value, then returns the specified axiom's config.
+ *
+ * @param axiomLabel - The axiom label to look up
+ * @param value - The value to check against
+ * @returns The matching axiom config or undefined
+ *
+ * @example
+ * ```typescript
+ * const idConfig = inferAxiom('Id', { id: 'test-123' })
+ * const typeConfig = inferAxiom('Type', { type: 'user' })
+ * ```
+ */
+export function inferAxiom<Label extends keyof Axioms>(
+  axiomLabel: Label,
+  value: unknown,
+): AxiomConfig | undefined {
+  const canon = inferCanon(value)
+
+  if (!canon) {
+    return undefined
+  }
+
+  return canon.axioms[axiomLabel as string]
+}

package/src/axioms/id.ts

@@ -0,0 +1,53 @@
+/**
+ * Id axiom implementation
+ *
+ * Provides universal access to entity identifiers across different data formats.
+ */
+
+import type { KeyNameAxiom, Satisfies } from '../types/index.js'
+import { inferAxiom } from '../axiom.js'
+
+/**
+ * Register Id axiom in global Axioms interface
+ */
+declare module '@relational-fabric/canon' {
+  interface Axioms {
+    /**
+     * Id concept - might be 'id', '@id', '_id', etc.
+     */
+    Id: KeyNameAxiom
+  }
+}
+
+/**
+ * Extract the ID value from any entity that satisfies the Id axiom
+ *
+ * @param x - The entity to extract ID from
+ * @returns The ID value as a string
+ *
+ * @example
+ * ```typescript
+ * const data = { id: 'test-123', name: 'Test' }
+ * const id = idOf(data) // "test-123"
+ * ```
+ */
+export function idOf<T extends Satisfies<'Id'>>(x: T): string {
+  const config = inferAxiom('Id', x)
+
+  if (!config) {
+    throw new Error('No matching canon found for Id axiom')
+  }
+
+  // For KeyNameAxiom, extract using the key field
+  if ('key' in config && typeof config.key === 'string') {
+    const value = (x as Record<string, unknown>)[config.key]
+
+    if (typeof value !== 'string') {
+      throw new TypeError(`Expected string ID, got ${typeof value}`)
+    }
+
+    return value
+  }
+
+  throw new Error('Invalid Id axiom configuration')
+}

package/src/axioms/references.ts

@@ -0,0 +1,98 @@
+/**
+ * References axiom implementation
+ *
+ * Provides universal access to entity references with format conversion.
+ */
+
+import type { EntityReference, RepresentationAxiom, Satisfies } from '../types/index.js'
+import { inferAxiom } from '../axiom.js'
+
+/**
+ * Register References axiom in global Axioms interface
+ */
+declare module '@relational-fabric/canon' {
+  interface Axioms {
+    /**
+     * References concept - might be string, object, etc.
+     */
+    References: RepresentationAxiom<string | object, EntityReference<string, unknown>>
+  }
+}
+
+/**
+ * Check if a value is a canonical reference (EntityReference object)
+ *
+ * @param value - The value to check
+ * @returns True if the value is an EntityReference object
+ */
+export function isCanonicalReference(
+  value: string | object,
+): value is EntityReference<string, unknown> {
+  return (
+    typeof value === 'object'
+    && value !== null
+    && 'ref' in value
+    && 'resolved' in value
+    && typeof (value as EntityReference<string, unknown>).ref === 'string'
+    && typeof (value as EntityReference<string, unknown>).resolved === 'boolean'
+  )
+}
+
+/**
+ * Extract and convert reference data to canonical EntityReference format
+ *
+ * @param x - The reference value to convert
+ * @returns The reference as an EntityReference object
+ *
+ * @example
+ * ```typescript
+ * const stringRef = 'user-123'
+ * const entityRef = { ref: 'user-123', resolved: false }
+ *
+ * console.log(referencesOf(stringRef)) // Converted to EntityReference
+ * console.log(referencesOf(entityRef)) // Already canonical EntityReference
+ * ```
+ */
+export function referencesOf<T extends Satisfies<'References'>>(
+  x: T,
+): EntityReference<string, unknown> {
+  const config = inferAxiom('References', x)
+
+  if (!config) {
+    throw new Error('No matching canon found for References axiom')
+  }
+
+  // Check if already canonical
+  if (isCanonicalReference(x)) {
+    return x
+  }
+
+  // Convert to canonical format
+  if (typeof x === 'string') {
+    return {
+      ref: x,
+      resolved: false,
+    }
+  }
+
+  if (typeof x === 'object' && x !== null) {
+    // Try to extract reference from object
+    const obj = x as Record<string, unknown>
+
+    // Look for common reference field names
+    const refFields = ['ref', 'id', 'reference', 'uri', 'url']
+    for (const field of refFields) {
+      if (field in obj && typeof obj[field] === 'string') {
+        return {
+          ref: obj[field] as string,
+          resolved: 'resolved' in obj ? Boolean(obj.resolved) : false,
+          value: 'value' in obj ? obj.value : undefined,
+        }
+      }
+    }
+
+    throw new TypeError(`Could not extract reference from object: ${JSON.stringify(x)}`)
+  }
+
+  throw new TypeError(`Expected string or object, got ${typeof x}`)
+}