@warlock.js/core 4.16.0 → 5.0.0

package/esm/warlock-config/normalize-build-config.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"normalize-build-config.mjs","names":[],"sources":["../../../../../../../core/src/warlock-config/normalize-build-config.ts"],"sourcesContent":["import type { WarlockConfig } from \"./types\";\n\ntype BuildConfig = NonNullable<WarlockConfig[\"build\"]>;\n\n/**\n * Fold the `outDirectory` alias into the canonical `outdir`.\n *\n * `outDirectory` is the name the documentation used for several releases\n * while the code only ever read `outdir`, so a config written from the docs\n * was silently ignored and the bundle still landed in `dist/`. Accepting both\n * keeps those configs working; `outdir` wins when both are set, since that is\n * the name esbuild uses and the one we tell people to prefer.\n *\n * Returns the input untouched when there is nothing to fold, so the common\n * case allocates nothing.\n */\nexport function normalizeBuildConfig<T extends BuildConfig>(build: T): T {\n  if (!build.outDirectory || build.outdir) {\n    return build;\n  }\n\n  return { ...build, outdir: build.outDirectory };\n}\n"],"mappings":";;;;;;;;;;;;;AAgBA,SAAgB,qBAA4C,OAAa;CACvE,IAAI,CAAC,MAAM,gBAAgB,MAAM,QAC/B,OAAO;CAGT,OAAO;EAAE,GAAG;EAAO,QAAQ,MAAM;CAAa;AAChD"}
+{"version":3,"file":"normalize-build-config.mjs","names":[],"sources":["../../../../../../../core/src/warlock-config/normalize-build-config.ts"],"sourcesContent":["import type { WarlockConfig } from \"./types\";\n\ntype BuildConfig = NonNullable<WarlockConfig[\"build\"]>;\n\n/**\n * Fold the `outDirectory` alias into the canonical `outdir`.\n *\n * `outDirectory` is the name the documentation used for several releases\n * while the code only ever read `outdir`, so a config written from the docs\n * was silently ignored and the bundle still landed in `dist/`. Accepting both\n * keeps those configs working; `outdir` wins when both are set, since that is\n * the name esbuild uses and the one we tell people to prefer.\n *\n * Returns the input untouched when there is nothing to fold, so the common\n * case allocates nothing.\n */\nexport function normalizeBuildConfig<T extends BuildConfig>(\n  build: T,\n): T & Pick<BuildConfig, \"outdir\"> {\n  if (!build.outDirectory || build.outdir) {\n    return build;\n  }\n\n  return { ...build, outdir: build.outDirectory };\n}\n"],"mappings":";;;;;;;;;;;;;AAgBA,SAAgB,qBACd,OACiC;CACjC,IAAI,CAAC,MAAM,gBAAgB,MAAM,QAC/B,OAAO;CAGT,OAAO;EAAE,GAAG;EAAO,QAAQ,MAAM;CAAa;AAChD"}

package/esm/warlock-config/types.d.mts

@@ -1,5 +1,6 @@
-import { CLICommand } from "../commands/cli-command.mjs";
 import { FileHealthCheckerContract } from "../dev-server/health-checker/file-health-checker.contract.mjs";
+import { Connector } from "../connectors/types.mjs";
+import { CLICommand } from "../commands/cli-command.mjs";
 import { MigrationConstructor } from "@warlock.js/cascade";
 import { BuildOptions } from "esbuild";
 
@@ -20,8 +21,16 @@ type WarlockConfig = {
   };
   /**
    * Build configuration
+   *
+   * `tsconfig` and `tsconfigRaw` are deliberately omitted alongside
+   * `entryPoints`. Either one applies the app's compiler options to EVERY
+   * file esbuild touches, workspace packages included — so an app-level
+   * `verbatimModuleSyntax: true` is imposed on package sources that were
+   * never written for it, and the bundle dies at import time with
+   * `Class extends value undefined`. The builder derives what it needs from
+   * the app's tsconfig itself (see `buildAliasMapFromTsconfig`).
    */
-  build?: Omit<BuildOptions, 'entryPoints'> & {
+  build?: Omit<BuildOptions, "entryPoints" | "tsconfig" | "tsconfigRaw"> & {
     /**
      * Output directory
      *
@@ -91,6 +100,31 @@ type WarlockConfig = {
      */
     sourcemap?: boolean | "inline" | "linked";
   };
+  /**
+   * Connectors this application adds beyond the built-in ones.
+   *
+   * ONE key drives both halves of a connector's life:
+   *
+   * - `warlock build` reads this array STATICALLY and drains each
+   *   connector's `build` contribution. It never calls `boot()`/`start()` —
+   *   listing a connector here does not run it.
+   * - `warlock dev` and the generated production entry register the same
+   *   array with the connectors manager, which is what actually boots it.
+   *
+   * A second key ("built for X" beside "boots X") was rejected precisely
+   * because the two would drift, and that drift is silent: a green build
+   * with no client bundle.
+   *
+   * @example
+   * ```typescript
+   * import { webConnector } from "@warlock.js/web/connector";
+   *
+   * export default defineConfig({
+   *   connectors: [webConnector({ pagesDirectory: "pages" })],
+   * });
+   * ```
+   */
+  connectors?: Connector[];
   /**
    * CLI configuration
    */

package/esm/warlock-config/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../core/src/warlock-config/types.ts"],"mappings":";;;;;;;;AAUA;;;KAAY,aAAA;EAaF;;;EATR,MAAA;IACE,IAAA;IACA,IAAA;IACA,cAAA;EAAA;EAFA;;;EAQF,KAAA,GAAQ,IAAA,CAAK,YAAA;IAAL;;;;;IAMN,MAAA;IAkDA;;;;;;;;;;IAvCA,YAAA;IAqFiB;;;;;IA/EjB,OAAA;IAwIA;;;;;;;AAuBO;;;;;;;;;IA9IP,YAAA;;;;;;;;;;;;;;;;IAgBA,OAAA;;;;;;IAMA,MAAA;;;;;;IAMA,SAAA;EAAA;;;;EAMF,GAAA;IACE,QAAA,GAAW,UAAA;EAAA;;;;EAMb,SAAA;;;;IAIE,KAAA;;;;;;MAME,OAAA;;;;;;MAMA,OAAA;IAAA;;;;IAKF,cAAA,GAAiB,yBAAA;;;;;IAKjB,eAAA;;;;;;;;;IASA,eAAA;;;;;;;;;IASA,qBAAA;;;;;;;;;;IAUA,mBAAA;EAAA;;;;EAMF,QAAA;;;;;;;;;;;;;;;;;;IAkBE,UAAA,GAAa,KAAA,CAAM,oBAAA;EAAA;;;;;;;EASrB,OAAA;;;;;;;IAOE,OAAA;;;;;;IAOA,OAAA;EAAA;AAAA"}
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../core/src/warlock-config/types.ts"],"mappings":";;;;;;;;;AAWA;;;KAAY,aAAA;EAqBF;;;EAjBR,MAAA;IACE,IAAA;IACA,IAAA;IACA,cAAA;EAAA;EAHF;;;;;;;;;;;EAiBA,KAAA,GAAQ,IAAA,CAAK,YAAA;IA8DX;;;;;IAxDA,MAAA;IA+FW;;;;;;;;;;IApFX,YAAA;IAsJF;;;;;IAhJE,OAAA;IAyLA;;AAAO;;;;;;;;;;;;;;IAxKP,YAAA;;;;;;;;;;;;;;;;IAgBA,OAAA;;;;;;IAMA,MAAA;;;;;;IAMA,SAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;EA2BF,UAAA,GAAa,SAAA;;;;EAKb,GAAA;IACE,QAAA,GAAW,UAAA;EAAA;;;;EAMb,SAAA;;;;IAIE,KAAA;;;;;;MAME,OAAA;;;;;;MAMA,OAAA;IAAA;;;;IAKF,cAAA,GAAiB,yBAAA;;;;;IAKjB,eAAA;;;;;;;;;IASA,eAAA;;;;;;;;;IASA,qBAAA;;;;;;;;;;IAUA,mBAAA;EAAA;;;;EAMF,QAAA;;;;;;;;;;;;;;;;;;IAkBE,UAAA,GAAa,KAAA,CAAM,oBAAA;EAAA;;;;;;;EASrB,OAAA;;;;;;;IAOE,OAAA;;;;;;IAOA,OAAA;EAAA;AAAA"}

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "@warlock.js/core",
   "description": "A robust nodejs framework for building blazing fast applications",
+  "warlock": {
+    "environment": "server"
+  },
   "bin": {
     "warlock": "bin/warlock.js"
   },
@@ -22,13 +25,13 @@
     "@mongez/slug": "^1.0.7",
     "@mongez/supportive-is": "^2.1.4",
     "@mongez/time-wizard": "^1.0.6",
-    "@warlock.js/auth": "4.16.0",
-    "@warlock.js/cache": "4.16.0",
-    "@warlock.js/cascade": "4.16.0",
-    "@warlock.js/context": "4.16.0",
-    "@warlock.js/logger": "4.16.0",
-    "@warlock.js/seal": "4.16.0",
-    "@warlock.js/fs": "4.16.0",
+    "@warlock.js/auth": "5.0.0",
+    "@warlock.js/cache": "5.0.0",
+    "@warlock.js/cascade": "5.0.0",
+    "@warlock.js/context": "5.0.0",
+    "@warlock.js/logger": "5.0.0",
+    "@warlock.js/seal": "5.0.0",
+    "@warlock.js/fs": "5.0.0",
     "chokidar": "^5.0.0",
     "dayjs": "^1.11.19",
     "es-module-lexer": "^2.0.0",
@@ -54,10 +57,10 @@
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
     "@react-email/render": "^2.0.5",
-    "@warlock.js/herald": "4.16.0",
-    "@warlock.js/ai": "4.16.0",
-    "@warlock.js/access": "4.16.0",
-    "@warlock.js/notifications": "4.16.0"
+    "@warlock.js/herald": "5.0.0",
+    "@warlock.js/ai": "5.0.0",
+    "@warlock.js/access": "5.0.0",
+    "@warlock.js/notifications": "5.0.0"
   },
   "peerDependenciesMeta": {
     "sharp": {
@@ -120,7 +123,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "4.16.0",
+  "version": "5.0.0",
   "type": "module",
   "main": "./esm/index.mjs",
   "module": "./esm/index.mjs",

package/skills/request-memo/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: request-memo
+description: 'Memoize async work for one HTTP request with `requestMemo<T>(key, fn)` — the v5 replacement for removed `fromRequest`, with single-flight promise sharing, settled-success reuse, rejection eviction, and no cross-request fallback. Triggers: `requestMemo`, `fromRequest`, `fromRequest removed`, `request-scoped cache`, `single-flight`, `current request memo`; "migrate off fromRequest", "load this once per request", "deduplicate concurrent loaders", "cache a repository lookup during one request"; typical import `import { requestMemo } from "@warlock.js/core"`. Skip: middleware-written request state — `@warlock.js/core/use-request-locals/SKILL.md`; process-wide or cross-request caching — `@warlock.js/core/use-middleware/SKILL.md`; competing patterns: dynamic `request[key]` properties, module-global `Map`, payload `request.get()` / `request.set()`.'
+---
+
+# Warlock — memoize work for one request
+
+`requestMemo()` is the v5 replacement for the removed `fromRequest()`. Use it when several code paths in the same HTTP request may need the same asynchronously computed value and the work should run once.
+
+## The exact signature
+
+From `core/src/http/context/request-memo.ts`:
+
+```ts
+export function requestMemo<T>(key: string, fn: () => Promise<T>): Promise<T>
+```
+
+Import it from the package root:
+
+```ts
+import { requestMemo } from "@warlock.js/core";
+```
+
+`fn` takes no arguments and must return a promise. Close over the current request or the inputs needed by the loader.
+
+## Migrate from v4 to v5
+
+### Before — v4 `fromRequest()`
+
+```ts title="src/app/tenants/utils/current-tenant.ts"
+import { fromRequest, type Request } from "@warlock.js/core";
+
+type Tenant = { id: string };
+
+async function loadTenant(id: string): Promise<Tenant> {
+  return { id };
+}
+
+export function currentTenant(request: Request): Promise<Tenant> {
+  const tenantId = String(request.header("x-tenant-id") ?? "");
+
+  return fromRequest("tenants.current", () => loadTenant(tenantId));
+}
+```
+
+### After — v5 `requestMemo()`
+
+```ts title="src/app/tenants/utils/current-tenant.ts"
+import { requestMemo, type Request } from "@warlock.js/core";
+
+type Tenant = { id: string };
+
+async function loadTenant(id: string): Promise<Tenant> {
+  return { id };
+}
+
+export function currentTenant(request: Request): Promise<Tenant> {
+  const tenantId = String(request.header("x-tenant-id") ?? "");
+
+  return requestMemo("tenants.current", () => loadTenant(tenantId));
+}
+```
+
+The call-site migration is usually the import and function name. The complete v5 example above also shows the callback-shape migration: if a v4 callback used the `Request` argument supplied by `fromRequest`, capture the surrounding `request` variable because `requestMemo`'s `fn` receives no arguments.
+
+## Single-flight behavior
+
+Within one request, the first call for a key invokes `fn` and stores its promise. Every concurrent caller using that key receives that exact promise, so parallel consumers do not duplicate the work. After the promise resolves, later calls during the same request keep receiving the cached successful promise.
+
+```ts title="src/app/catalog/controllers/show-product.controller.ts"
+import { requestMemo, type RequestHandler } from "@warlock.js/core";
+
+let loads = 0;
+
+async function loadProduct(): Promise<{ id: string }> {
+  loads += 1;
+  return { id: "product-1" };
+}
+
+export const showProductController: RequestHandler = async ({ response }) => {
+  const first = requestMemo("catalog.product", loadProduct);
+  const second = requestMemo("catalog.product", loadProduct);
+  const [product, sameProduct] = await Promise.all([first, second]);
+
+  return response.success({ product, sameProduct, loads });
+};
+```
+
+For that request, `first === second` and `loads` is `1`.
+
+A rejection is not cached. The rejected entry is deleted immediately, so a later call with the same key retries `fn`. Callers already sharing the rejected promise all observe that rejection.
+
+## Lifetime and isolation
+
+The memo table is attached indirectly to the current request-context store through a `WeakMap`. Each incoming request gets a fresh store, so:
+
+- two concurrent requests never share entries, even when they use the same key;
+- resolved values live only for the request's context lifetime;
+- the store and its memo entries are eligible for garbage collection after the request ends;
+- no value is written onto the `Request` object.
+
+Calling `requestMemo()` outside the HTTP request pipeline throws synchronously. It deliberately has no process-global fallback. For data meant to survive across requests, use an explicit application cache instead.
+
+## Why it replaces `fromRequest()`
+
+`fromRequest()` memoized through dynamic `request[key]` properties. That only type-checked because v4's `Request` had a `[key: string]: any` index signature. v5 removed both the unsafe index signature and `fromRequest()`; `requestMemo()` keeps the one-request lifetime without mutating `Request` or turning values into `any`.
+
+The new helper also provides real single-flight behavior: it stores the in-flight promise. The old helper awaited its callback before writing the result onto `Request`, so concurrent v4 callers could run the same callback more than once.
+
+## Key design
+
+Keys share one string namespace within a request. Use stable, namespaced keys and include every input that changes the result:
+
+```ts
+import { requestMemo } from "@warlock.js/core";
+
+type Product = { id: string };
+
+async function findProduct(id: string): Promise<Product> {
+  return { id };
+}
+
+export function productById(id: string): Promise<Product> {
+  return requestMemo(`catalog.product:${id}`, () => findProduct(id));
+}
+```
+
+Reusing one key for different result types is a caller bug: TypeScript cannot compare the generic type arguments used at separate call sites.
+
+## Gotchas
+
+- **Do not call it during bootstrap, in a CLI command, or from a background job.** There is no active HTTP request context there, so it throws.
+- **Do not omit result-changing inputs from the key.** `catalog.product` is wrong when different IDs may be loaded during one request; use `catalog.product:${id}`.
+- **Do not use `request.set()` as a replacement.** It writes to the request input payload read by `all()`, `input()`, and `validated()`.
+- **Failures retry.** If repeated failures must also be cached, this primitive is not that policy; catch and convert the failure into a successful result deliberately, or use another cache.
+- **Use `request.locals` for state written by middleware and read downstream.** Memoization and request attachment are separate jobs.
+
+## See also
+
+- [`use-request-locals/SKILL.md`](../use-request-locals/SKILL.md) — typed per-request data written by middleware.
+- [`write-middleware/SKILL.md`](../write-middleware/SKILL.md) — authoring and registering middleware.
+- [`create-controller/SKILL.md`](../create-controller/SKILL.md) — consuming request-scoped values from controllers.

package/skills/use-request-locals/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: use-request-locals
+description: 'Carry typed, server-only data through one HTTP request with `request.locals`, usually written by middleware and read by downstream middleware or controllers. Augment `RequestLocals` in the module that owns each key; v5 no longer permits arbitrary `request.foo` properties. Triggers: `request.locals`, `RequestLocals`, `request.post`, `request.organization`, `Property does not exist on type Request`, `Request index signature`; "attach data to a request", "share middleware data with a controller", "type request locals", "migrate dynamic request properties"; typical type augmentation `declare module "@warlock.js/core" { interface RequestLocals { ... } }`. Skip: computed-on-demand single-flight values and removed `fromRequest` — `@warlock.js/core/request-memo/SKILL.md`; middleware mechanics — `@warlock.js/core/write-middleware/SKILL.md`; authenticated user typing — augment `RequestUser`, not `RequestLocals`; competing patterns: `(request as any).foo`, `request.set()`, module-global mutable state.'
+---
+
+# Warlock — use typed request locals
+
+`request.locals` is the v5 home for private data that middleware writes and downstream code reads during the same request. It is separate from client input and starts as a fresh object on every `Request` instance.
+
+## The exact declarations
+
+From `core/src/http/types.ts`:
+
+```ts
+export interface RequestLocals {}
+```
+
+From `core/src/http/request.ts`:
+
+```ts
+public locals: RequestLocals = {};
+```
+
+`RequestLocals` is intentionally empty and augmentable. It has no index signature: declare owned keys explicitly so reads and writes have their real types instead of `any`.
+
+## Migrate a middleware attachment from v4 to v5
+
+### Before — v4 dynamic `Request` property
+
+```ts title="src/app/observability/middleware/request-timing.middleware.ts"
+import type { Middleware } from "@warlock.js/core";
+
+export const requestTimingMiddleware: Middleware = request => {
+  request.startedAt = Date.now();
+};
+```
+
+```ts title="src/app/observability/controllers/timing.controller.ts"
+import type { RequestHandler } from "@warlock.js/core";
+
+export const timingController: RequestHandler = async (request, response) => {
+  return response.success({ elapsedMs: Date.now() - request.startedAt });
+};
+```
+
+Those arbitrary properties compiled in v4 because `Request` had a `[key: string]: any` index signature. That signature is gone in v5.
+
+### After — v5 typed `request.locals`
+
+Declare the key once in the feature that owns and writes it:
+
+```ts title="src/app/observability/request-locals.d.ts"
+declare module "@warlock.js/core" {
+  interface RequestLocals {
+    startedAt?: number;
+  }
+}
+
+export {};
+```
+
+Write it in middleware:
+
+```ts title="src/app/observability/middleware/request-timing.middleware.ts"
+import type { Middleware } from "@warlock.js/core";
+
+export const requestTimingMiddleware: Middleware = ({ request }) => {
+  request.locals.startedAt = Date.now();
+};
+```
+
+Read it downstream:
+
+```ts title="src/app/observability/controllers/timing.controller.ts"
+import type { RequestHandler } from "@warlock.js/core";
+
+export const timingController: RequestHandler = async ({ request, response }) => {
+  const startedAt = request.locals.startedAt;
+
+  if (startedAt === undefined) {
+    return response.serverError({ error: "request timing middleware did not run" });
+  }
+
+  return response.success({ elapsedMs: Date.now() - startedAt });
+};
+```
+
+The `?` is honest about runtime ordering: the type exists everywhere, but the value exists only after the middleware runs. Narrow it downstream unless every construction path guarantees initialization and your project deliberately declares the key as required.
+
+## Augment with an application type
+
+An augmentation file may import the value's type. Keeping the declaration beside the writer makes ownership visible and prevents unrelated packages from claiming the same key.
+
+```ts title="src/app/organizations/request-locals.d.ts"
+import type { Organization } from "./models/organization";
+
+declare module "@warlock.js/core" {
+  interface RequestLocals {
+    organization?: Organization;
+  }
+}
+
+export {};
+```
+
+The module specifier must be `"@warlock.js/core"`, matching the public package import whose `RequestLocals` interface is exported. Ensure the `.d.ts` file is included by the application's TypeScript configuration.
+
+## What belongs in `locals`
+
+Good fits are values explicitly produced by one stage and consumed by later stages:
+
+- a resolved organization, session, feature flag, or authorization subject;
+- request timing or tracing metadata;
+- a model loaded by validation or routing middleware;
+- private server state that must not appear in request input.
+
+`locals` is not a cache API. If consumers should be able to ask for a value independently and concurrent calls must collapse into one loader, use `requestMemo()` instead.
+
+## Isolation from input and other requests
+
+`Request` initializes `locals` with `{}` for each new request. Request instances are not pooled, so values cannot carry into the next request.
+
+Writing `request.locals.organization` does not affect `request.all()`, `request.input()`, or `request.validated()`. By contrast, `request.set()` writes into the input payload's `all` bag, so it is the wrong replacement for a private v4 attachment.
+
+## Choosing the extension surface
+
+- Use `request.locals` for per-request data written by middleware and read downstream.
+- Use `requestMemo(key, fn)` for lazily computed, single-flight work scoped to the active request.
+- Augment `Request` itself only for a genuine new typed member that also has a runtime implementation.
+- Augment `RequestUser` for the authenticated `request.user` shape; do not duplicate it under locals merely to work around typing.
+
+## Gotchas
+
+- **Do not restore `(request as any).post`.** It recreates the exact unchecked behavior v5 removed.
+- **Do not add `[key: string]: any` to `RequestLocals`.** Declare each key with its actual type; otherwise every typo becomes valid again.
+- **Do not centralize keys owned by unrelated features.** The middleware or package that writes a key should own its augmentation.
+- **Do not assume an optional local was initialized.** Middleware registration and ordering are runtime concerns; narrow the value or fail clearly downstream.
+- **Avoid key collisions across augmentations.** Interface merging requires repeated property declarations to agree, but stable feature-prefixed names are clearer for generic metadata.
+
+## See also
+
+- [`request-memo/SKILL.md`](../request-memo/SKILL.md) — the `fromRequest()` migration and single-flight request memoization.
+- [`write-middleware/SKILL.md`](../write-middleware/SKILL.md) — middleware execution and registration.
+- [`create-controller/SKILL.md`](../create-controller/SKILL.md) — reading locals in downstream controllers.