@reventlessdev/reventless-infra 3.0.0-alpha.96 → 3.0.0-alpha.97

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.97 (2026-07-11)
+
+### Features
+
+* **infra:** add DeployBootstrap seam for generated deploy programs ([f0dc868](https://github.com/ReventlessDev/reventless-core/commit/f0dc8686396d21e7b39667eb0825b2e57fe4dabf))
+
+
 # 3.0.0-alpha.96 (2026-07-11)
 
 **Note:** Version bump only for package @reventlessdev/reventless-infra

package/README.md

@@ -0,0 +1,92 @@
+[![npm](https://img.shields.io/npm/v/@reventlessdev/reventless-infra.svg?label=npm)](https://www.npmjs.com/package/@reventlessdev/reventless-infra)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Docs](https://img.shields.io/badge/docs-reventless.dev-blue)](https://docs.reventless.dev)
+
+# @reventlessdev/reventless-infra
+
+> ⚠️ **Alpha.** APIs and on-disk formats can change without notice between releases.
+> Pin exact versions and expect breaking changes.
+
+The **infrastructure type layer** of [Reventless](https://docs.reventless.dev) — a
+spec-driven, event-sourced CQRS framework written in [ReScript](https://rescript-lang.org).
+This package defines the deploy-time infrastructure types and abstract `Platform` interface
+that are shared across storage/cloud adapters, so plugin-assembly code can be written once
+against provider-agnostic types and satisfied by any concrete adapter. It uses
+[Pulumi](https://www.pulumi.com) types for deploy-time resource references. Modules are
+exposed under the `ReventlessInfra` namespace.
+
+## What it provides
+
+ReScript modules, consumed by adding the package to your `rescript.json` `dependencies`.
+
+**Platform interface & adapters (`types/`, `adapter/`)**
+
+- **`Platform`** — the abstract factory interface for platform-agnostic component assembly.
+  Plugin code takes a `Platform.T` as a functor argument; a concrete adapter (e.g.
+  `reventless-aws`) supplies the implementation at the composition root.
+- **`Adapter`** — deploy-time infrastructure primitives: `resource` (fields wrapped in
+  `Pulumi.Output.t`), `resolvedResource` (runtime values), and `resourceInfo` describing a
+  resource's structural role (storage keys, stream source, API resolver).
+- **`ResourceNaming`** — provider-agnostic operations for validating and deriving
+  URN-safe resource names.
+- **`ExtensionMapping`** / **`ExtensionPointMapping`** — the action types that route commands
+  and events between an extension and the extension point it wraps.
+- **`Message`**, **`PluginExtensionPointSpec`**, **`NoEventMappings`** — supporting types for
+  message identity and plugin/extension wiring.
+
+**Component types (`components/`)**
+
+Deploy-time `outputs` (infrastructure references) and runtime `operations` for each Reventless
+component kind — **`Component`** (the typed wrapper around a Pulumi `ComponentResource`),
+**`Plugin`**, **`Aggregate`**, **`ReadModel`**, **`EventLog`** / **`DcbEventLog`**,
+**`CommandTopic`** / **`EventTopic`**, **`CommandGenerator`**, **`EventCollector`**,
+**`EventMapper`**, **`QueryDb`**, **`Api`**, **`Task`**, **`ExtensionPoint`** / **`Extension`**,
+**`Scheduler`**, **`Heartbeat`**, and the DCB slices.
+
+## Where it fits
+
+`reventless-infra` sits between the specification layer and the concrete adapters:
+
+```
+reventless-spec (specifications)
+  ↓
+reventless-infra (shared infrastructure types)  ← this package
+  ↓
+reventless-aws / reventless-postgres / reventless-local (storage & deployment adapters)
+```
+
+- It builds on
+  [`@reventlessdev/reventless-spec`](https://www.npmjs.com/package/@reventlessdev/reventless-spec)
+  for the domain contracts.
+- Adapters such as
+  [`@reventlessdev/reventless-aws`](https://www.npmjs.com/package/@reventlessdev/reventless-aws)
+  provide the concrete `Platform.T` implementation these types describe.
+
+You normally obtain `reventless-infra` transitively by scaffolding an app rather than
+installing it on its own.
+
+## Install
+
+```bash
+pnpm add @reventlessdev/reventless-infra
+```
+
+Then register it as a ReScript dependency in `rescript.json`:
+
+```json
+{
+  "dependencies": ["@reventlessdev/reventless-infra"]
+}
+```
+
+Requires ReScript `^12.3.0` (peer dependency).
+
+## Links
+
+- 📚 Documentation — [docs.reventless.dev](https://docs.reventless.dev)
+- 📦 Repository — [ReventlessDev/reventless-core](https://github.com/ReventlessDev/reventless-core)
+- 📋 [Changelog](./CHANGELOG.md)
+
+## License
+
+[Apache-2.0](https://opensource.org/licenses/Apache-2.0)

package/package.json

@@ -1,19 +1,29 @@
 {
   "name": "@reventlessdev/reventless-infra",
-  "version": "3.0.0-alpha.96",
+  "version": "3.0.0-alpha.97",
   "description": "Infrastructure types for Reventless framework",
   "license": "Apache-2.0",
+  "jest": {
+    "testMatch": [
+      "<rootDir>/tests/**/*Test.res.mjs"
+    ],
+    "moduleFileExtensions": [
+      "js",
+      "mjs"
+    ]
+  },
   "dependencies": {
     "sury": "11.0.0-alpha.4",
     "sury-ppx": "11.0.0-alpha.2",
     "uuid": "^13.0.0",
-    "@reventlessdev/rescript-effect": "0.1.0-alpha.26",
-    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.14",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.74",
-    "@reventlessdev/rescript-uuid": "1.1.0-alpha.14"
+    "@reventlessdev/rescript-effect": "0.1.0-alpha.27",
+    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.15",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.75",
+    "@reventlessdev/rescript-uuid": "1.1.0-alpha.15"
   },
   "devDependencies": {
-    "rescript": "^12.3.0"
+    "rescript": "^12.3.0",
+    "@reventlessdev/rescript-jest": "1.0.0-alpha.7"
   },
   "peerDependencies": {
     "rescript": "^12.3.0"
@@ -30,6 +40,7 @@
     "build": "rescript build",
     "start": "rescript watch",
     "clean": "rescript clean",
-    "rebuild": "pnpm run clean && pnpm run build"
+    "rebuild": "pnpm run clean && pnpm run build",
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest"
   }
 }

package/rescript.json

@@ -15,6 +15,11 @@
     {
       "dir": "src",
       "subdirs": true
+    },
+    {
+      "dir": "tests",
+      "subdirs": true,
+      "type": "dev"
     }
   ],
   "dependencies": [
@@ -22,7 +27,8 @@
     "@reventlessdev/rescript-pulumi-pulumi",
     "@reventlessdev/rescript-effect",
     "@reventlessdev/rescript-uuid",
-    "@reventlessdev/reventless-spec"
+    "@reventlessdev/reventless-spec",
+    "@reventlessdev/rescript-jest"
   ],
   "suffix": ".res.mjs"
 }

package/src/components/DeployBootstrap.res

@@ -0,0 +1,83 @@
+/**
+Deploy-time bootstrap seam: a named choke point through which a deploy program
+runs cross-cutting activations at fixed phases, without hand-editing the
+generated `Main.res`.
+
+No-op by default. Zero registrations ⇒ `run` does nothing ⇒ existing generated
+and hand-written deploy programs are byte-identical and preview with no resource
+diff. An extension (a backend, an operational package) registers a contribution
+via `register` — at module-load time as an import side effect, or explicitly —
+and the generated program's `run(PreDeploy)` / `run(PostDeploy)` calls fire it in
+registration order.
+
+Same shape as `ReventlessCore.Monitoring.use`: a module-level registry consulted
+by an emitted call, so deploy-time extension becomes *registration*, not *file
+editing*. See `docs/plans/deploy-bootstrap-seam.md`.
+*/
+
+/**
+Ordered phases at which bootstrap contributions run during a deploy program.
+*/
+type phase =
+  | /** before `deployPlatform` / `deployPlugin` — seam registration and other
+       ordering-sensitive activations that must precede the platform/plugin
+       graph build */
+  PreDeploy
+  | /** after the platform/plugin graph is registered — exports, cross-stack
+       output emission */
+  PostDeploy
+
+type contribution = unit => unit
+
+let preContributions: ref<array<contribution>> = ref([])
+let postContributions: ref<array<contribution>> = ref([])
+let preRan = ref(false)
+let postRan = ref(false)
+
+let registryFor = phase =>
+  switch phase {
+  | PreDeploy => preContributions
+  | PostDeploy => postContributions
+  }
+
+let ranFor = phase =>
+  switch phase {
+  | PreDeploy => preRan
+  | PostDeploy => postRan
+  }
+
+/**
+Register a contribution. Contributions run in registration order within a phase.
+Safe to call at module-load time (as an import side effect) or explicitly.
+Defaults to `PreDeploy`.
+*/
+let register = (~phase=PreDeploy, contribution: contribution) => {
+  let registry = registryFor(phase)
+  registry := registry.contents->Array.concat([contribution])
+}
+
+/**
+Run all contributions registered for a phase, in registration order. Emitted by
+generated deploy programs around the platform/plugin build. Idempotent per phase:
+running an already-run phase is a no-op, and running a phase with no
+registrations does nothing.
+*/
+let run = (phase: phase) => {
+  let ran = ranFor(phase)
+  if !ran.contents {
+    ran := true
+    registryFor(phase).contents->Array.forEach(contribution => contribution())
+  }
+}
+
+/**
+Reset all registries and run-flags. Test-support only — deploy programs never
+call this. Lets a test exercise registration order, phase isolation, and
+idempotency from a clean slate.
+*/
+let reset = () => {
+  preContributions := []
+  postContributions := []
+  preRan := false
+  postRan := false
+}

package/src/components/DeployBootstrap.res.mjs

@@ -0,0 +1,69 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+
+let preContributions = {
+  contents: []
+};
+
+let postContributions = {
+  contents: []
+};
+
+let preRan = {
+  contents: false
+};
+
+let postRan = {
+  contents: false
+};
+
+function registryFor(phase) {
+  if (phase === "PreDeploy") {
+    return preContributions;
+  } else {
+    return postContributions;
+  }
+}
+
+function ranFor(phase) {
+  if (phase === "PreDeploy") {
+    return preRan;
+  } else {
+    return postRan;
+  }
+}
+
+function register(phaseOpt, contribution) {
+  let phase = phaseOpt !== undefined ? phaseOpt : "PreDeploy";
+  let registry = registryFor(phase);
+  registry.contents = registry.contents.concat([contribution]);
+}
+
+function run(phase) {
+  let ran = ranFor(phase);
+  if (!ran.contents) {
+    ran.contents = true;
+    registryFor(phase).contents.forEach(contribution => contribution());
+    return;
+  }
+}
+
+function reset() {
+  preContributions.contents = [];
+  postContributions.contents = [];
+  preRan.contents = false;
+  postRan.contents = false;
+}
+
+export {
+  preContributions,
+  postContributions,
+  preRan,
+  postRan,
+  registryFor,
+  ranFor,
+  register,
+  run,
+  reset,
+}
+/* No side effect */

package/tests/DeployBootstrapTest.res

@@ -0,0 +1,72 @@
+open JestGlobals
+
+module DB = DeployBootstrap
+
+describe("DeployBootstrap", () => {
+  // The seam holds module-level state, so each case resets first for isolation.
+  describe("run with no registrations", () => {
+    testSync("is a no-op that does not throw", () => {
+      DB.reset()
+      DB.run(PreDeploy)
+      DB.run(PostDeploy)
+      expect(true)->toBe(true)
+    })
+  })
+
+  describe("registration order within a phase", () => {
+    testSync("runs contributions in the order they were registered", () => {
+      DB.reset()
+      let calls = []
+      DB.register(() => calls->Array.push("a"))
+      DB.register(() => calls->Array.push("b"))
+      DB.register(() => calls->Array.push("c"))
+      DB.run(PreDeploy)
+      expect(calls)->toEqual(["a", "b", "c"])
+    })
+  })
+
+  describe("phase isolation", () => {
+    testSync("run(PreDeploy) fires only PreDeploy contributions", () => {
+      DB.reset()
+      let calls = []
+      DB.register(~phase=PreDeploy, () => calls->Array.push("pre"))
+      DB.register(~phase=PostDeploy, () => calls->Array.push("post"))
+      DB.run(PreDeploy)
+      expect(calls)->toEqual(["pre"])
+      DB.run(PostDeploy)
+      expect(calls)->toEqual(["pre", "post"])
+    })
+
+    testSync("defaults to PreDeploy when no phase is given", () => {
+      DB.reset()
+      let calls = []
+      DB.register(() => calls->Array.push("default"))
+      DB.run(PostDeploy)
+      expect(calls)->toEqual([])
+      DB.run(PreDeploy)
+      expect(calls)->toEqual(["default"])
+    })
+  })
+
+  describe("idempotent run per phase", () => {
+    testSync("running an already-run phase does nothing", () => {
+      DB.reset()
+      let count = ref(0)
+      DB.register(() => count := count.contents + 1)
+      DB.run(PreDeploy)
+      DB.run(PreDeploy)
+      DB.run(PreDeploy)
+      expect(count.contents)->toBe(1)
+    })
+
+    testSync("a contribution registered after run does not fire", () => {
+      DB.reset()
+      let calls = []
+      DB.register(() => calls->Array.push("before"))
+      DB.run(PreDeploy)
+      DB.register(() => calls->Array.push("after"))
+      DB.run(PreDeploy)
+      expect(calls)->toEqual(["before"])
+    })
+  })
+})

package/tests/DeployBootstrapTest.res.mjs

@@ -0,0 +1,100 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as DeployBootstrap$ReventlessInfra from "../src/components/DeployBootstrap.res.mjs";
+
+globalThis.describe("DeployBootstrap", () => {
+  globalThis.describe("run with no registrations", () => {
+    globalThis.test("is a no-op that does not throw", () => {
+      DeployBootstrap$ReventlessInfra.reset();
+      DeployBootstrap$ReventlessInfra.run("PreDeploy");
+      DeployBootstrap$ReventlessInfra.run("PostDeploy");
+      globalThis.expect(true).toBe(true);
+    });
+  });
+  globalThis.describe("registration order within a phase", () => {
+    globalThis.test("runs contributions in the order they were registered", () => {
+      DeployBootstrap$ReventlessInfra.reset();
+      let calls = [];
+      DeployBootstrap$ReventlessInfra.register(undefined, () => {
+        calls.push("a");
+      });
+      DeployBootstrap$ReventlessInfra.register(undefined, () => {
+        calls.push("b");
+      });
+      DeployBootstrap$ReventlessInfra.register(undefined, () => {
+        calls.push("c");
+      });
+      DeployBootstrap$ReventlessInfra.run("PreDeploy");
+      globalThis.expect(calls).toEqual([
+        "a",
+        "b",
+        "c"
+      ]);
+    });
+  });
+  globalThis.describe("phase isolation", () => {
+    globalThis.test("run(PreDeploy) fires only PreDeploy contributions", () => {
+      DeployBootstrap$ReventlessInfra.reset();
+      let calls = [];
+      DeployBootstrap$ReventlessInfra.register("PreDeploy", () => {
+        calls.push("pre");
+      });
+      DeployBootstrap$ReventlessInfra.register("PostDeploy", () => {
+        calls.push("post");
+      });
+      DeployBootstrap$ReventlessInfra.run("PreDeploy");
+      globalThis.expect(calls).toEqual(["pre"]);
+      DeployBootstrap$ReventlessInfra.run("PostDeploy");
+      globalThis.expect(calls).toEqual([
+        "pre",
+        "post"
+      ]);
+    });
+    globalThis.test("defaults to PreDeploy when no phase is given", () => {
+      DeployBootstrap$ReventlessInfra.reset();
+      let calls = [];
+      DeployBootstrap$ReventlessInfra.register(undefined, () => {
+        calls.push("default");
+      });
+      DeployBootstrap$ReventlessInfra.run("PostDeploy");
+      globalThis.expect(calls).toEqual([]);
+      DeployBootstrap$ReventlessInfra.run("PreDeploy");
+      globalThis.expect(calls).toEqual(["default"]);
+    });
+  });
+  globalThis.describe("idempotent run per phase", () => {
+    globalThis.test("running an already-run phase does nothing", () => {
+      DeployBootstrap$ReventlessInfra.reset();
+      let count = {
+        contents: 0
+      };
+      DeployBootstrap$ReventlessInfra.register(undefined, () => {
+        count.contents = count.contents + 1 | 0;
+      });
+      DeployBootstrap$ReventlessInfra.run("PreDeploy");
+      DeployBootstrap$ReventlessInfra.run("PreDeploy");
+      DeployBootstrap$ReventlessInfra.run("PreDeploy");
+      globalThis.expect(count.contents).toBe(1);
+    });
+    globalThis.test("a contribution registered after run does not fire", () => {
+      DeployBootstrap$ReventlessInfra.reset();
+      let calls = [];
+      DeployBootstrap$ReventlessInfra.register(undefined, () => {
+        calls.push("before");
+      });
+      DeployBootstrap$ReventlessInfra.run("PreDeploy");
+      DeployBootstrap$ReventlessInfra.register(undefined, () => {
+        calls.push("after");
+      });
+      DeployBootstrap$ReventlessInfra.run("PreDeploy");
+      globalThis.expect(calls).toEqual(["before"]);
+    });
+  });
+});
+
+let DB;
+
+export {
+  DB,
+}
+/*  Not a pure module */