@bronti/wooter 0.0.0-stage → 6.0.0

package/src/MiddlewareContext.ts

@@ -0,0 +1,216 @@
+import type { EmptyObject, State } from "./types/types.ts";
+import RouteContext, {
+  HandlerDidntRespondError,
+  type InternalHandler,
+  RouteContext__execution,
+  RouteContext__respond,
+} from "./RouteContext.ts";
+import WooterError from "./WooterError.ts";
+import { err, ok, type Result } from "./export/result.ts";
+
+/**
+ * Error thrown when middleware exits without delegating to `next()`.
+ */
+export class MiddlewareHandlerDidntCallUpError extends WooterError {
+  /** Error name used for identification. */
+  override name: string = "MiddlewareHandlerDidntCallUpError";
+
+  constructor() {
+    super("The middleware handler must call ctx.next() before exiting");
+  }
+}
+
+/**
+ * Middleware context passed to middleware handlers.
+ *
+ * Extends {@link RouteContext} with flow-control helpers for composing middleware chains.
+ *
+ * @typeParam TParams Route param shape.
+ * @typeParam TState State currently available on the context.
+ * @typeParam TNextState State shape that this middleware can pass to the next handler.
+ */
+export default class MiddlewareContext<
+  TParams extends Record<string, unknown> | undefined = undefined,
+  TState extends State | undefined = undefined,
+  TNextState extends State | undefined = undefined,
+> extends RouteContext<TParams, TState> {
+  /**
+   * @internal
+   * Internal marker that tracks whether `next()` or `tryNext()` has been called.
+   */
+  private calledNext = false;
+
+  /**
+   * @internal
+   * Creates a middleware context instance.
+   *
+   * @param request Current request.
+   * @param state Context state.
+   * @param params Route params.
+   * @param nextHandler Internal continuation handler.
+   */
+  constructor(
+    override readonly request: Request,
+    state: TState extends undefined ? EmptyObject : TState,
+    params: TParams extends undefined ? EmptyObject : TParams,
+    private readonly nextHandler: InternalHandler,
+    reporter: (e: unknown) => void,
+  ) {
+    super(request, state, params, reporter);
+  }
+
+  /**
+   * Invokes the next handler in the middleware chain.
+   *
+   * @param state State to merge into downstream context.
+   * @param request Optional request override.
+   * @returns The downstream response, or throws the downstream error.
+   */
+  readonly next = async (
+    state: TNextState extends undefined ? EmptyObject : TNextState,
+    request?: Request,
+  ): Promise<Response> => {
+    const opt = await this.tryNext(state, request);
+    return opt.match(
+      (c) => {
+        return c;
+      },
+      (e) => {
+        throw e;
+      },
+    );
+  };
+
+  /**
+   * Like {@link next}, but captures failures in a `Result`.
+   *
+   * @param state State to merge into downstream context.
+   * @param request Optional request override.
+   * @returns `ok(response)` on success or `err(error)` on failure.
+   */
+  readonly tryNext = (
+    state: TNextState extends undefined ? EmptyObject : TNextState,
+    request?: Request,
+  ): Promise<Result<Response, unknown>> => {
+    const { promise, resolve } =
+      Promise.withResolvers<Result<Response, unknown>>();
+    this.calledNext = true;
+    const ctx = this.nextHandler(state, request || this.request, this.reporter);
+    this[RouteContext__respond].then((response) => {
+      if (!ctx[RouteContext__respond].resolved) {
+        ctx[RouteContext__respond].push(response);
+      }
+    });
+    ctx[RouteContext__respond].then((response) => {
+      resolve(ok(response));
+    });
+    ctx[RouteContext__execution].then((v) => {
+      v.inspect((e) => {
+        if (
+          e instanceof HandlerDidntRespondError &&
+          this.respondSoon.resolved
+        ) {
+          this[RouteContext__respond].then((response) => {
+            resolve(ok(response));
+          });
+          return;
+        }
+        resolve(err(e));
+      });
+    });
+    return promise;
+  };
+
+  /**
+   * Invokes {@link next} and immediately responds with the downstream response.
+   *
+   * @param state State to merge into downstream context.
+   * @param request Optional request override.
+   * @returns The response sent by `resp`.
+   */
+  readonly forward = (
+    state: TNextState extends undefined ? EmptyObject : TNextState,
+    request?: Request,
+  ): Promise<Response> =>
+    this.next(state, request).then((response) =>
+      this.respondSoon.resolved ? response : this.resp(response),
+    );
+
+  /**
+   * Invokes {@link tryNext} and maps successful responses through `resp`.
+   *
+   * @param state State to merge into downstream context.
+   * @param request Optional request override.
+   * @returns Result containing the response or captured error.
+   */
+  readonly tryForward = (
+    state: TNextState extends undefined ? EmptyObject : TNextState,
+    request?: Request,
+  ): Promise<Result<Response, unknown>> =>
+    this.tryNext(state, request).then((o) =>
+      o.map((response) =>
+        this.respondSoon.resolved ? response : this.resp(response),
+      ),
+    );
+
+  /**
+   * Adapts a middleware handler into the router's internal handler signature.
+   *
+   * @param handler User middleware handler.
+   * @param params Route params for the current match.
+   * @param next Continuation for the next link in the chain.
+   * @returns Internal handler that executes middleware and reports lifecycle errors.
+   *
+   * @internal
+   */
+  static useMiddlewareHandler<
+    TParams extends Record<string, unknown> = Record<string, unknown>,
+    TState extends State | undefined = undefined,
+    TNextState extends State | undefined = undefined,
+  >(
+    handler: MiddlewareHandler<TParams, TState, TNextState>,
+    params: Record<string, unknown>,
+    next: InternalHandler,
+    reporter: (e: unknown) => void,
+  ): InternalHandler {
+    return (state, req) => {
+      const ctx = new MiddlewareContext<TParams, TState, TNextState>(
+        req,
+        state as TState extends undefined ? EmptyObject : TState,
+        params as TParams extends undefined ? EmptyObject : TParams,
+        next,
+        reporter,
+      );
+
+      Promise.try(handler, ctx).then(
+        () => {
+          if (!ctx.respondSoon.resolved) {
+            if (!ctx.calledNext)
+              return ctx.catchErr(new MiddlewareHandlerDidntCallUpError());
+            return ctx.catchErr(new HandlerDidntRespondError());
+          }
+          ctx.ok();
+        },
+        (e) => {
+          ctx.catchErr(e);
+        },
+      );
+
+      return ctx as unknown as MiddlewareContext;
+    };
+  }
+}
+
+/**
+ * Middleware handler function.
+ *
+ * @param ctx Middleware context.
+ * @returns Optional promise for async middleware.
+ */
+export type MiddlewareHandler<
+  TParams extends Record<string, unknown> = Record<string, unknown>,
+  TState extends State | undefined = undefined,
+  TNextState extends State | undefined = undefined,
+> = (
+  ctx: MiddlewareContext<TParams, TState, TNextState>,
+) => Promise<unknown> | unknown;

package/src/RouteContext.ts

@@ -0,0 +1,312 @@
+import { none, type Option, some } from "./export/option.ts";
+import { Soon } from "@bronti/robust/Soon";
+import type { EmptyObject, State } from "./types/types.ts";
+import WooterError, { ControlFlowBreak } from "./WooterError.ts";
+import { TypedMap } from "@bronti/robust/TypedMap";
+
+/**
+ * Error thrown when a handler exits without calling `resp()`.
+ */
+export class HandlerDidntRespondError extends WooterError {
+  /** Error name used for identification. */
+  override name: string = "HandlerDidntRespondError";
+
+  constructor() {
+    super("The handler must respond before exiting");
+  }
+}
+
+/**
+ * Error thrown when a handler attempts to respond more than once.
+ */
+export class HandlerRespondedTwiceError extends WooterError {
+  /** Error name used for identification. */
+  override name: string = "HandlerRespondedTwiceError";
+
+  constructor() {
+    super("The handler called resp() multiple times");
+  }
+}
+
+/**
+ * Internal symbol for reading a context's execution state.
+ */
+export const RouteContext__execution = Symbol("RouteContext__execution");
+
+/**
+ * Internal symbol for reading a context's response state.
+ */
+export const RouteContext__respond = Symbol("RouteContext__respond");
+
+/**
+ * Internal symbol for reading a context's stray-error reporter.
+ */
+export const RouteContext__reporter = Symbol("RouteContext__reporter");
+/**
+ * Context passed to route handlers.
+ *
+ * @typeParam TParams Route param shape.
+ * @typeParam TState State shape accumulated from middleware.
+ */
+export default class RouteContext<
+  TParams extends Record<string, unknown> | undefined = undefined,
+  TState extends State | undefined = undefined,
+> {
+  /**
+   * Backing store for context state.
+   */
+  private readonly _state: TState extends undefined ? EmptyObject : TState;
+
+  /**
+   * Backing store for route params.
+   */
+  private readonly _params: TypedMap<
+    TParams extends undefined ? EmptyObject : TParams
+  >;
+
+  /**
+   * Middleware state available to the current handler.
+   *
+   * @returns The typed context state object.
+   */
+  get state(): TState extends undefined ? EmptyObject : TState {
+    return this._state;
+  }
+
+  /**
+   * Route params captured from path matching.
+   *
+   * @returns Typed map of route params.
+   */
+  get params(): TypedMap<TParams extends undefined ? EmptyObject : TParams> {
+    return this._params;
+  }
+
+  /**
+   * Tracks handler completion state.
+   *
+   * `none()` means successful completion, `some(error)` means failure.
+   *
+   * @internal
+   */
+  protected executionSoon: Soon<Option<unknown>> = new Soon();
+
+  /**
+   * Tracks the first response emitted by this context.
+   *
+   * @internal
+   */
+  protected respondSoon: Soon<Response> = new Soon();
+
+  /**
+   * Exposes {@link executionSoon} through a symbol-based internal API.
+   *
+   * @internal
+   */
+  get [RouteContext__execution](): RouteContext["executionSoon"] {
+    return this.executionSoon;
+  }
+
+  /**
+   * Exposes {@link respondSoon} through a symbol-based internal API.
+   *
+   * @internal
+   */
+  get [RouteContext__respond](): RouteContext["respondSoon"] {
+    return this.respondSoon;
+  }
+
+  /**
+   * Exposes the stray-error reporter through a symbol-based internal API.
+   *
+   * @internal
+   */
+  get [RouteContext__reporter](): (e: unknown) => void {
+    return this.reporter;
+  }
+
+  /**
+   * Indicates if a response has already been sent.
+   */
+  get responded(): boolean {
+    return this.respondSoon.resolved;
+  }
+
+  /**
+   * Parsed request URL.
+   */
+  readonly url: URL;
+
+  /**
+   * Creates a route context.
+   *
+   * @param request Incoming request.
+   * @param state Context state from middleware.
+   * @param params Route params captured by path matching.
+   *
+   * @internal
+   */
+  constructor(
+    /** Request object. */
+    readonly request: Request,
+    state: TState extends undefined ? EmptyObject : TState,
+    params: TParams extends undefined ? EmptyObject : TParams,
+    protected reporter: (e: unknown) => void,
+  ) {
+    this.url = new URL(request.url);
+    this._state = state;
+    this._params = new TypedMap(params);
+  }
+
+  /**
+   * Marks execution as failed with an error.
+   *
+   * @param e Error value.
+   *
+   * @internal
+   */
+  protected err(e: unknown) {
+    this.executionSoon.push(some(e));
+  }
+
+  /**
+   * Marks the handler as successfully completed.
+   *
+   * This is typically called by the internal runtime after handler execution settles.
+   *
+   * @returns `void`.
+   */
+  readonly ok = (): void => {
+    if (!this.respondSoon.resolved)
+      return this.err(new HandlerDidntRespondError());
+    this.executionSoon.push(none());
+  };
+
+  /**
+   * Responds to the request.
+   *
+   * @param response A fully constructed response.
+   * @param init Optional response init when the first argument is body-like.
+   * @returns The response that was sent.
+   * @throws HandlerRespondedTwiceError If called after a previous response.
+   */
+  readonly resp: {
+    (response: Response): Response;
+    (body?: BodyInit | null, init?: ResponseInit): Response;
+  } = (responseOrBody, init?: ResponseInit): Response => {
+    const response =
+      responseOrBody instanceof Response
+        ? responseOrBody
+        : new Response(responseOrBody, init);
+    if (this.executionSoon.resolved) {
+      console.warn(
+        "responding after execution is misuse of the wooter library",
+      );
+      return response;
+    }
+    if (this.respondSoon.resolved) {
+      throw new HandlerRespondedTwiceError();
+    }
+
+    this.respondSoon.push(response);
+    return response;
+  };
+
+  /**
+   * Responds with a JSON body.
+   *
+   * @param data JSON-serializable response body.
+   * @param init Optional response init.
+   * @returns The response that was sent.
+   */
+  readonly respJson: typeof Response.json = (data, init) =>
+    this.resp(Response.json(data, init));
+
+  /**
+   * Safely exits handler execution without surfacing a framework error.
+   *
+   * Call this when you intentionally stop processing after sending a response.
+   *
+   * @throws ControlFlowBreak Always throws to abort current control flow.
+   */
+  readonly safeExit = (): never => {
+    throw ControlFlowBreak;
+  };
+
+  /**
+   * Captures an internal handler error and routes it to the appropriate sink.
+   *
+   * @param e Error value.
+   *
+   * @internal
+   */
+  protected catchErr = (e: unknown): void => {
+    if (this.respondSoon.resolved) {
+      if (e != ControlFlowBreak) this.reporter(e);
+      return this.ok();
+    }
+
+    this.err(e);
+  };
+
+  /**
+   * Adapts a user route handler into the internal runtime handler signature.
+   *
+   * @param handler Route handler to wrap.
+   * @param params Route params for the current match.
+   * @returns Internal handler that manages lifecycle success/error state.
+   *
+   * @internal
+   */
+  static useRouteHandler<
+    TParams extends Record<string, unknown> | undefined = Record<
+      string,
+      unknown
+    >,
+    TState extends State | undefined = State,
+  >(
+    handler: RouteHandler<TParams, TState>,
+    params: Record<string, unknown>,
+    reporter: (e: unknown) => void,
+  ): InternalHandler {
+    return (state, req) => {
+      const ctx = new RouteContext<TParams, TState>(
+        req,
+        state as TState extends undefined ? EmptyObject : TState,
+        params as TParams extends undefined ? EmptyObject : TParams,
+        reporter,
+      );
+
+      Promise.try(handler, ctx).then(
+        () => {
+          ctx.ok();
+        },
+        (e) => {
+          ctx.catchErr(e);
+        },
+      );
+
+      return ctx as unknown as RouteContext;
+    };
+  }
+}
+
+/**
+ * Internal route handler signature used by the execution pipeline.
+ */
+export type InternalHandler = (
+  state: State,
+  request: Request,
+  reporter: (e: unknown) => void,
+) => RouteContext;
+
+/**
+ * Route handler function.
+ *
+ * @param ctx Route context.
+ * @returns Optional promise for async handlers.
+ */
+export type RouteHandler<
+  TParams extends Record<string, unknown> | undefined = Record<string, unknown>,
+  TState extends State | undefined = State,
+> = (ctx: RouteContext<TParams, TState>) => Promise<unknown> | unknown;