A practical aLib implementation for the ReScript ecosystem: a proving ground + adapter layer that brings together ReScript stdlib direction, Melange compatibility, and optional Proven validation — while staying upstream-first and reversible.

• Status
• The “no tears” contract
• What this repo is
• What this repo is NOT
• Why Common + Specific?
• Relationship to aggregate-library
• Proven integration (optional)
• Repo structure (suggested)
• Adoption strategy
• Graduation / retirement policy
• Contributing
• License

Alpha / opt-in / namespaced.

This repo is not a replacement standard library.

We commit to:

• Namespacing: All public APIs live under a clear prefix (e.g. Aggregate. / Alib.). No shadowing of Option, Result, Array, etc.

• Upstream-first: @rescript/core / compiler Stdlib and Melange Stdlib remain the sources of truth.

• Reversible adoption: Per-file, per-module adoption; easy to remove.

• Optional validation: Proven-powered checks are opt-in entrypoints, not required usage.

• Deletion-friendly: Anything that graduates upstream is deprecated and removed here to avoid long-term duplication.

This is the ecosystem implementation of the aLib method for ReScript developers.

It provides:

• A Common layer: utilities and patterns that work cleanly across ReScript + Melange constraints.

• A Specific layer: ReScript-centric ergonomics and higher-level helpers that are intentionally not “common”.

• Compatibility adapters: explicit conversions/escape hatches to/from upstream types and runtime modules.

• Optional Proven integration: safer boundaries for FFI / JSON / external data during development.

• Not “the new ReScript stdlib”.

• Not a fork of upstream stdlibs.

• Not a mandate for compiler/tooling direction.

• Not required for library authors.

This repo is deliberately split so we can:

• keep a small “Common” surface stable and testable,

• iterate on “Specific” without fear of fragmenting the ecosystem,

• and propose upstream changes selectively (only where maintainers want them).

“Common” here means: common to ReScript + Melange usage patterns we support, not universal across all languages or all runtimes.

aggregate-library is the methods + stress-test lab: overlap demos and extreme constraints.

This repo is the practical application for the ReScript community: it uses the method (clear boundaries + tests + reversibility), but targets real ReScript/Melange workflows.

Proven is supported only where it improves boundary safety (FFI/JSON/untyped data).

Rules:

• Proven entrypoints are opt-in (e.g. fromJsonWithSchema).

• Non-Proven paths remain first-class and documented.

• Proven usage should be easy to remove without redesigning code.

Per-file adoption:

1. Import one namespaced module in one file.

2. Keep upstream stdlib everywhere else.

3. Convert at boundaries only (via compat/ helpers).

4. If you stop using aLib, remove it cleanly.

Each module has one of these outcomes:

• Experiment: fast iteration, namespaced, obvious warnings in docs.

• Stable: semver discipline + tests.

• Propose upstream: only if maintainers want it and it fits upstream goals.

• Upstreamed: deprecate here, remove here, keep only adapters if needed.

• Remain here: if it is inherently ecosystem glue (adapters, codemods, boundary helpers).

We prefer contributions that reduce long-term maintenance load:

• small modules with explicit upstream mapping,

• clear docs for boundary behavior,

• tests for stabilization,

• and reversible changes.

PLMP-1.0.0-or-later