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

This project is licensed under the Mozilla Public License, v. 2.0. See the LICENSE file for details.

SPDX-License-Identifier: MPL-2.0

Changelog

See CHANGELOG.md for release history.

Architecture

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