@rexezuge/runtime 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,81 @@
+# @rexezuge/runtime
+
+DI container, configuration, worker bases, logger, and KV cache for Cloudflare Workers.
+
+Zero dependencies (the one platform import is type-only, resolved through each consumer's generated wrangler types).
+
+```bash
+pnpm add @rexezuge/runtime
+```
+
+---
+
+## 1. DI — `Container` / `Token` / `RequestScope`
+
+Minimal by design: factory + singleton scopes, branded tokens for inference, nothing else.
+
+```ts
+import { Container, type Token } from '@rexezuge/runtime';
+
+interface Mailer { send(to: string): Promise<void> }
+const MailerToken: Token<Mailer> = 'Mailer';
+
+const root = new Container().bindValue(MailerToken, new SmtpMailer());
+const mailer = root.get(MailerToken); // Mailer, no explicit generic needed
+```
+
+Composition roots wire implementations once; request handlers resolve via `asScopedContext` / `getRequestScope` rather than passing a container through business logic.
+
+## 2. Config — `AppConfiguration` / `EnvParser`
+
+Consumers subclass `AppConfiguration` and compose their own typed sections (limits, auth, replication), each reading env once through `EnvParser`:
+
+```ts
+import { AppConfiguration, EnvParser } from '@rexezuge/runtime';
+
+class MyConfig extends AppConfiguration {
+  public getPageSize(): number {
+    return EnvParser.number(this.raw(), 'PAGE_SIZE', 50);
+  }
+}
+
+const config = MyConfig.fromEnv(env);
+for (const warning of config.validate()) console.warn(warning); // warnings, never throws
+```
+
+`getSiteUrl()` strips trailing slashes so callers can concatenate paths. `validate()` returns startup warnings (e.g. `DEMO_MODE` in production) instead of throwing a 500 on a request path.
+
+## 3. Worker bases
+
+| Base | Extends for |
+| --- | --- |
+| `AbstractEntrypointWorker` | HTTP + cron entrypoints (`onRequest` / `onScheduled`) |
+| `AbstractDurableObjectWorker` | Durable Object workers |
+| `AbstractQueueWorker` | Queue consumers |
+| `AbstractWorkflowWorker` | Workflows |
+
+`fetch()` / `scheduled()` log-and-contain: an unhandled throw is a 500 response or a logged cron failure, never a platform crash. There is deliberately no `/__scheduled` HTTP branch — cron runs through the wrangler `triggers.crons` binding. The structural `WorkerExecutionContext` / `WorkerScheduledController` types mean this package typechecks without `@cloudflare/workers-types`.
+
+## 4. Logger and KV cache
+
+```ts
+import { createLogger, KvCache } from '@rexezuge/runtime';
+
+const logger = createLogger('Sync', 'my-repo', env); // level from env.LOG_LEVEL ?? process.env, defaults to info
+logger.info('starting sync');
+
+const cache = new KvCache(env.CACHE); // fail-soft: reads null, writes false, D1/DO stay authoritative
+await cache.putText('session', 'sess:abc', 'payload', { ttlSeconds: 300 });
+```
+
+`KV_DOMAINS` / `buildKvKey` / `clampTtl` keep every repo's key shapes and TTL ceilings identical.
+
+---
+
+## Verifying this package
+
+```bash
+pnpm --filter @rexezuge/runtime exec tsc -p tsconfig.json
+pnpm --filter @rexezuge/runtime typecheck
+pnpm --filter @rexezuge/runtime test
+```

package/dist/config/EnvParser.d.ts

@@ -22,6 +22,15 @@ declare class EnvParser {
      */
     static isValidPositiveInt(env: unknown, key: string): boolean;
     static string(env: unknown, key: string, defaultValue: string): string;
+    /**
+     * A non-negative integer, zero included.
+     *
+     * Distinct from `positiveInt` because zero is a meaningful configuration for
+     * retention and quota knobs ("keep nothing"), and a parser that rejected it
+     * would silently substitute the default — so setting `0` in the dashboard
+     * would appear to do nothing at all.
+     */
+    static nonNegativeInt(env: unknown, key: string, defaultValue: string): number;
     static boolean(env: unknown, key: string, defaultValue: string): boolean;
     /** The raw value, or undefined when unset. Public because presence checks (validate) need it. */
     static readString(env: unknown, key: string): string | undefined;

package/dist/config/EnvParser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EnvParser.d.ts","sourceRoot":"","sources":["../../src/config/EnvParser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,cAAM,SAAS;WACC,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;IAMlF;;;;;;;OAOG;WACW,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;WAOtD,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;WAI/D,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO;IAI/E,iGAAiG;WACnF,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;CAGxE;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}
+{"version":3,"file":"EnvParser.d.ts","sourceRoot":"","sources":["../../src/config/EnvParser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,cAAM,SAAS;WACC,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;IAMlF;;;;;;;OAOG;WACW,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;WAOtD,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;IAI7E;;;;;;;OAOG;WACW,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;WAMvE,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO;IAI/E,iGAAiG;WACnF,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;CAGxE;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}

package/dist/config/EnvParser.js

@@ -34,6 +34,19 @@ class EnvParser {
     static string(env, key, defaultValue) {
         return this.readString(env, key) ?? defaultValue;
     }
+    /**
+     * A non-negative integer, zero included.
+     *
+     * Distinct from `positiveInt` because zero is a meaningful configuration for
+     * retention and quota knobs ("keep nothing"), and a parser that rejected it
+     * would silently substitute the default — so setting `0` in the dashboard
+     * would appear to do nothing at all.
+     */
+    static nonNegativeInt(env, key, defaultValue) {
+        const value = this.readString(env, key);
+        const parsed = Number(value ?? defaultValue);
+        return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : Number(defaultValue);
+    }
     static boolean(env, key, defaultValue) {
         return (this.readString(env, key) ?? defaultValue) === 'true';
     }

package/dist/config/EnvParser.js.map

@@ -1 +1 @@
-{"version":3,"file":"EnvParser.js","sourceRoot":"","sources":["../../src/config/EnvParser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,SAAS;IACN,MAAM,CAAC,WAAW,CAAC,GAAY,EAAE,GAAW,EAAE,YAAoB;QACvE,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACxC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,IAAI,YAAY,CAAC,CAAC;QAC7C,OAAO,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IACpF,CAAC;IAED;;;;;;;OAOG;IACI,MAAM,CAAC,kBAAkB,CAAC,GAAY,EAAE,GAAW;QACxD,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACxC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACrC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC7B,OAAO,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,CAAC;IACpD,CAAC;IAEM,MAAM,CAAC,MAAM,CAAC,GAAY,EAAE,GAAW,EAAE,YAAoB;QAClE,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,YAAY,CAAC;IACnD,CAAC;IAEM,MAAM,CAAC,OAAO,CAAC,GAAY,EAAE,GAAW,EAAE,YAAoB;QACnE,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,YAAY,CAAC,KAAK,MAAM,CAAC;IAChE,CAAC;IAED,iGAAiG;IAC1F,MAAM,CAAC,UAAU,CAAC,GAAY,EAAE,GAAW;QAChD,OAAQ,GAA0C,CAAC,GAAG,CAAC,CAAC;IAC1D,CAAC;CACF;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}
+{"version":3,"file":"EnvParser.js","sourceRoot":"","sources":["../../src/config/EnvParser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,SAAS;IACN,MAAM,CAAC,WAAW,CAAC,GAAY,EAAE,GAAW,EAAE,YAAoB;QACvE,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACxC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,IAAI,YAAY,CAAC,CAAC;QAC7C,OAAO,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IACpF,CAAC;IAED;;;;;;;OAOG;IACI,MAAM,CAAC,kBAAkB,CAAC,GAAY,EAAE,GAAW;QACxD,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACxC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACrC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC7B,OAAO,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,CAAC;IACpD,CAAC;IAEM,MAAM,CAAC,MAAM,CAAC,GAAY,EAAE,GAAW,EAAE,YAAoB;QAClE,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,YAAY,CAAC;IACnD,CAAC;IAED;;;;;;;OAOG;IACI,MAAM,CAAC,cAAc,CAAC,GAAY,EAAE,GAAW,EAAE,YAAoB;QAC1E,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACxC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,IAAI,YAAY,CAAC,CAAC;QAC7C,OAAO,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IACrF,CAAC;IAEM,MAAM,CAAC,OAAO,CAAC,GAAY,EAAE,GAAW,EAAE,YAAoB;QACnE,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,YAAY,CAAC,KAAK,MAAM,CAAC;IAChE,CAAC;IAED,iGAAiG;IAC1F,MAAM,CAAC,UAAU,CAAC,GAAY,EAAE,GAAW;QAChD,OAAQ,GAA0C,CAAC,GAAG,CAAC,CAAC;IAC1D,CAAC;CACF;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rexezuge/runtime",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -29,6 +29,7 @@
     "typescript": "6.0.3",
     "vitest": "4.1.11"
   },
+  "description": "DI container, configuration, worker bases, logger, and KV cache for Cloudflare Workers.",
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.test.json --noEmit",