Preference Injector

A powerful, type-safe preference injection system for dynamic configuration management.

Built with ReScript and Deno following the Hyperpolymath Language Standard.

Features

• Multiple Providers: File-based, environment variables, API, and in-memory storage

• Priority System: Resolve conflicts between providers using customizable strategies

• Type Safety: Full ReScript type safety with pattern matching

• Caching: LRU and TTL caching strategies for performance

• Validation: Schema-based and custom validation rules

• Encryption: AES-256-GCM encryption for sensitive preferences

• Audit Logging: Track all preference operations

• Migrations: Version and migrate preference schemas

• CRDT Support: Distributed preference synchronization

• Post-Quantum Crypto: Future-proof cryptographic operations

Language Policy

This project follows the Hyperpolymath Language Standard:

Allowed	Banned
ReScript	TypeScript
Deno	Node.js, npm, bun
Rust (for extensions)	Go, Python (except SaltStack)
Nickel (configuration)	Makefile

Installation

Prerequisites

• Deno >= 1.40.0

• ReScript >= 11.0.0

• Just (for task running)

Setup

# Clone the repository
git clone https://github.com/hyperpolymath/preference-injector.git
cd preference-injector

# Build ReScript code
just build

# Run tests
just test

Quick Start

open Types
open Injector

// Create an injector with configuration
let injector = make(
  ~config=Some({
    conflictResolution: Some(HighestPriority),
    enableCache: Some(true),
    cacheTTL: Some(3600000),
    enableValidation: Some(true),
    enableEncryption: None,
    enableAudit: Some(true),
    encryptionKey: None,
  }),
)

// Create a memory provider
let memProvider = MemoryProvider.make(~priority=Normal)

// Add provider and initialize
addProvider(injector, provider)
await initialize(injector)

// Set preferences
switch await set(injector, "theme", String("dark"), None) {
| Ok() => Js.Console.log("Theme set!")
| Error(e) => Js.Console.error(e.message)
}

// Get preferences
switch await get(injector, "theme", None) {
| Ok(String(value)) => Js.Console.log(`Theme: ${value}`)
| Ok(_) => Js.Console.error("Unexpected type")
| Error(e) => Js.Console.error(e.message)
}

Providers

Memory Provider

In-memory storage for runtime preferences:

let provider = MemoryProvider.make(~priority=Normal)

File Provider

JSON or .env file-based storage:

let provider = FileProvider.make(
  ~config={
    filePath: "./config.json",
    priority: Normal,
    format: JSON,
    watchForChanges: true,
  }
)

Environment Provider

Environment variable integration:

let provider = EnvProvider.make(
  ~config=Some({
    prefix: Some("APP_"),
    priority: Highest,
    parseValues: true,
  })
)

API Provider

Remote configuration service:

let provider = ApiProvider.make(
  ~config={
    baseUrl: "https://config.example.com",
    apiKey: Some("your-api-key"),
    headers: Js.Dict.empty(),
    priority: Normal,
    timeout: 5000,
    retries: 3,
  }
)

Validation

Add validation rules to ensure preference values are valid:

// Add validation rules
addValidationRule(injector, "email", Validator.CommonRules.email())
addValidationRule(injector, "age", Validator.CommonRules.numberRange(~min=0.0, ~max=150.0))
addValidationRule(injector, "username", Validator.CommonRules.stringLength(~min=3, ~max=20))

CRDT Support

Distributed preference synchronization with conflict-free replicated data types:

• G-Counter: Grow-only counter

• PN-Counter: Positive-negative counter

• LWW-Register: Last-writer-wins register

• LWW-Map: Last-writer-wins map

• OR-Set: Observed-remove set

Cryptography

Modern cryptographic primitives (RSR-compliant, no MD5/SHA1):

• Hashing: SHA-256, SHA-512, BLAKE3

• Encryption: AES-256-GCM

• Signatures: ECDSA (P-256, P-384)

• Key Exchange: ECDH

• Post-Quantum: Kyber support planned

Development

Build

just build        # Build ReScript code
just build-clean  # Clean and rebuild

Test

just test         # Run all tests
just test-rescript  # Run ReScript tests
just test-coverage  # Run with coverage

CI Pipeline

just ci           # Full CI pipeline (clean, build, lint, test, verify)
just rsr-verify   # RSR Framework compliance check

Project Structure

preference-injector/
├── src/rescript/           # ReScript source code
│   ├── core/               # Core injector logic
│   ├── providers/          # Preference providers
│   ├── utils/              # Utility functions
│   ├── types/              # Type definitions
│   ├── errors/             # Error handling
│   ├── crdt/               # CRDT implementations
│   └── crypto/             # Cryptographic utilities
├── tests/rescript/         # ReScript tests
├── examples/               # Usage examples
├── docs/                   # Documentation
├── deno.json               # Deno configuration
├── bsconfig.json           # ReScript configuration
├── justfile                # Just task runner
├── Mustfile.epx            # Deployment state contract
└── config.ncl              # Nickel configuration

Configuration

Configuration is managed via Nickel (config.ncl) for type-safe, validated settings.

just nickel-check   # Validate Nickel config
just nickel-export  # Export to JSON

API Documentation

See the API Documentation for detailed API reference.

Examples

Check the examples/ directory for usage examples:

• basic_usage.res - Basic preference management

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Important: All contributions must follow the Hyperpolymath Language Policy. TypeScript, Node.js, npm, and Makefile contributions will be rejected.

License

MIT - See LICENSE.txt

Dual-licensed under Palimpsest License for special use cases.

Changelog

See CHANGELOG.md for release history.

Architecture

See TOPOLOGY.md for a visual architecture map and completion dashboard.