@lambdot/env 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.2.0
+
+### Patch Changes
+
+- Updated dependencies [[`71e5732`](https://github.com/Embers-of-the-Fire/lambdot/commit/71e57321ad4ec7d1aef3651d104123f8167ec2e7), [`71e5732`](https://github.com/Embers-of-the-Fire/lambdot/commit/71e57321ad4ec7d1aef3651d104123f8167ec2e7)]:
+  - @lambdot/core@0.2.0
+
+## 0.1.1
+
+### Patch Changes
+
+- [#10](https://github.com/Embers-of-the-Fire/lambdot/pull/10) [`19d37e4`](https://github.com/Embers-of-the-Fire/lambdot/commit/19d37e42c7a5514fb62c8f31c65e1aa01916d355) Thanks [@Embers-of-the-Fire](https://github.com/Embers-of-the-Fire)! - Switch inter-package dependency pins from exact versions to `workspace:*` so workspace members always resolve against local sources during development; pnpm rewrites the protocol to exact versions at pack/publish time.
+- Updated dependencies [[`19d37e4`](https://github.com/Embers-of-the-Fire/lambdot/commit/19d37e42c7a5514fb62c8f31c65e1aa01916d355)]:
+  - @lambdot/core@0.1.1
+
 ## [0.1.0](https://github.com/Embers-of-the-Fire/lambdot/compare/env-v0.0.1...env-v0.1.0) (2026-08-29)
 
 

package/README.md

@@ -0,0 +1,64 @@
+# @lambdot/env
+
+Reads variables from `process.env` into a typed namespace, so deployments
+pass configuration through the environment and plugins consume it through
+the composition's visible context — with the provider-before-consumer
+ordering checked at compile time.
+
+## What it provides
+
+- **One plugin factory.** `envVars(name, keys)` reads each key from
+  `process.env` at activation and emits the snapshot —
+  `Readonly<Record<TKey, string>>` — under `name`. A missing or empty
+  variable throws during activation, so a misconfigured deployment fails
+  loudly before any consumer activates.
+- **A typed namespace value.** Because the keys are a type parameter,
+  consumers read `ctx["qq-env"].QQ_BOT_APP_ID` as `string` with no casts.
+  The name is a parameter too, so instances multiply: two providers compose
+  side by side under distinct names, exactly like `wsTransport` in
+  `@lambdot/websocket`.
+
+## Usage
+
+```ts
+import { createKernel, definePlugin } from "@lambdot/core";
+import { envVars } from "@lambdot/env";
+
+const report = definePlugin({
+    name: "report",
+    apply(input: { "qq-env": Readonly<Record<"QQ_BOT_APP_ID" | "QQ_BOT_APP_SECRET", string>> }) {
+        const appId: string = input["qq-env"].QQ_BOT_APP_ID;
+        // ...
+    },
+});
+
+const kernel = createKernel()
+    .use(envVars("qq-env", ["QQ_BOT_APP_ID", "QQ_BOT_APP_SECRET"]))
+    .use(report); // before envVars: compile error — the mapping's ctx is
+// typed as what's visible so far, and "qq-env" isn't in it
+```
+
+Consumers may also declare a wider view — any
+`Readonly<Record<string, string>>` under the same namespace key — since the
+emitted record stays assignable to it; `@lambdot/protocol-qq`'s plugins
+consume `{ env: Readonly<Record<string, string>> }` this way, wired with an
+explicit `mapping: (ctx) => ({ env: ctx["qq-env"] })`. Workers have no
+`process.env`; `@lambdot/host-cloudflare` ships a counterpart `envVars`
+that reads from a worker's bindings object into the same record shape.
+
+## API
+
+- `envVars<const TName extends string, const TKey extends string>(name: TName, keys: readonly TKey[])` —
+  returns a `Plugin<void, Readonly<Record<TKey, string>>, void, TName>`. The
+  snapshot is taken once in `apply`; the plugin takes no config.
+
+## Examples
+
+- [qq-gateway-bot](../../../examples/qq-gateway-bot) — `envVars("qq-env", ...)`
+  feeds the qq platform's api plugin through its `mapping`.
+- [qq-webhook-bot](../../../examples/qq-webhook-bot) — the same env wiring over
+  webhooks.
+
+## License
+
+Dual-licensed under [Apache-2.0](../../../LICENSE-APACHE) and [MIT](../../../LICENSE-MIT).

package/package.json

@@ -1,14 +1,19 @@
 {
-    "name": "@lambdot/env",
-    "version": "0.1.0",
-    "type": "module",
-    "exports": {
-        ".": "./src/index.ts"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
-    "dependencies": {
-        "@lambdot/core": "workspace:*"
-    }
-}
+  "name": "@lambdot/env",
+  "version": "0.2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Embers-of-the-Fire/lambdot",
+    "directory": "packages/core/env"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@lambdot/core": "0.2.0"
+  }
+}

package/src/index.ts

@@ -1,20 +1,10 @@
-import type { Disposer, FeaturePlugin } from "@lambdot/core";
+import type { Plugin } from "@lambdot/core";
+import { definePlugin } from "@lambdot/core";
 
 /**
- * The typed capability contract shared by an environment provider and its
- * consumers, parameterized by capability name: the provider declares it as
- * `TProvides`, consumers as `TInjects`. The value is a snapshot of the
- * requested variables, keyed by variable name. Distinct names fold side by
- * side (`EnvCapability<"qq-env"> & EnvCapability<"discord-env">`), exactly
- * like `WsCapability` in `@lambdot/websocket`.
- */
-export type EnvCapability<TCap extends string, TKey extends string> = {
-    readonly [K in TCap]: Readonly<Record<TKey, string>>;
-};
-
-/**
- * Read variables from `process.env` and provide them as a typed capability.
- * A missing or empty variable fails activation loudly at kernel start, so a
+ * Read variables from `process.env` and emit them as the plugin's namespace
+ * value: a snapshot of the requested variables, keyed by variable name. A
+ * missing or empty variable fails activation loudly at start, so a
  * misconfigured deployment surfaces before any consumer activates.
  *
  * ```ts
@@ -22,29 +12,23 @@ export type EnvCapability<TCap extends string, TKey extends string> = {
  * // ctx["qq-env"].QQ_BOT_APP_ID: string
  * ```
  */
-export function envVars<TCap extends string, TKey extends string>(
+export function envVars<const TCap extends string, const TKey extends string>(
     capability: TCap,
     keys: readonly TKey[],
-): FeaturePlugin<{}, {}, undefined, void, `env:${TCap}`, EnvCapability<TCap, TKey>> {
-    return {
-        name: `env:${capability}`,
-        apply(ctx) {
+): Plugin<void, Readonly<Record<TKey, string>>, void, TCap> {
+    return definePlugin({
+        name: capability,
+        apply() {
             const values: Record<string, string> = {};
             for (const key of keys) {
                 const value = process.env[key];
                 if (value === undefined || value === "")
                     throw new Error(
-                        `env:${capability}: required environment variable "${key}" is not set`,
+                        `${capability}: required environment variable "${key}" is not set`,
                     );
                 values[key] = value;
             }
-            // The kernel's `provide` keeps its value parameter behind a
-            // conditional type that stays deferred for a generic capability
-            // name; `EnvCapability<TCap, TKey>` already ties this name to the
-            // record, so pin the call down here (same trick as `wsTransport`).
-            return (
-                ctx.provide as (name: TCap, value: Readonly<Record<TKey, string>>) => Disposer
-            ).call(ctx, capability, values as Readonly<Record<TKey, string>>);
+            return values as Readonly<Record<TKey, string>>;
         },
-    };
+    });
 }