expediate 0.0.3 → 1.0.1

package/dist/apis.d.ts

@@ -0,0 +1,166 @@
+import type { RouterRequest, Router } from './router.js';
+/**
+ * An API error thrown (or rejected) by a service method.
+ *
+ * When a service method throws or rejects with an object of this shape, the
+ * framework translates it into an HTTP error response automatically:
+ * - `httpStatus` → HTTP status code (defaults to `500`).
+ * - `data`       → JSON-serialised response body (takes precedence over `message`).
+ * - `message`    → Plain-text response body.
+ */
+export interface ApiError {
+    /** HTTP status code to send (e.g. `404`, `503`). Defaults to `500`. */
+    httpStatus?: number;
+    /** Structured error payload; serialised to JSON when present. */
+    data?: unknown;
+    /** Human-readable error message used when `data` is absent. */
+    message?: string;
+}
+/**
+ * A service method handler.
+ *
+ * Called with `this` bound to the current service instance.
+ *
+ * @param params - Route parameters extracted from the URL (e.g. `{ uid: '42' }`),
+ *                 merged with URL query-string parameters.
+ * @param body   - Parsed request body (populated by a body-parsing middleware
+ *                 such as `json()`).
+ * @returns The value to send as the JSON response body, a `Promise` of the
+ *          same, or `undefined` / `null` / any falsy value to send **201 No
+ *          Content** (useful for mutations that produce no response body).
+ */
+export type ServiceMethod<TInstance = ServiceInstance> = (this: TInstance, params: Record<string, string>, body?: unknown) => unknown | Promise<unknown>;
+/**
+ * The runtime state object that backs a service instance.
+ *
+ * Produced by `service.data()` and extended with the methods from
+ * `service.methods` before `service.setup()` is called.  A hidden `$key`
+ * property carries the scope key when `data()` is not supplied.
+ */
+export type ServiceInstance = Record<string, unknown> & {
+    /** The scope key used to identify this instance (set by the framework). */
+    $key?: string | null;
+};
+/**
+ * A named map of method functions to mix into every service instance.
+ *
+ * Methods declared here are copied onto the instance object, bound to `this`,
+ * so they can call each other and read/write instance state naturally.
+ */
+export type ServiceMethods<TInstance extends ServiceInstance = ServiceInstance> = {
+    [name: string]: (this: TInstance, ...args: unknown[]) => unknown;
+};
+/**
+ * A route map: keys are Express-style path patterns, values are handler
+ * functions that are invoked with `this` bound to the service instance.
+ */
+export type RouteMap<TInstance extends ServiceInstance = ServiceInstance> = {
+    [path: string]: ServiceMethod<TInstance>;
+};
+/**
+ * A service definition object — the single argument to {@link apiBuilder}.
+ *
+ * A service declares its state, helper methods, and HTTP route handlers in
+ * one cohesive object.  The framework instantiates the service (once globally
+ * for a singleton, or per-scope key), mixes in the helper methods, runs
+ * `setup()`, then calls the appropriate route handler for each HTTP request.
+ *
+ * **Scoping:**
+ * - When `scope` is **absent** (or not a function), the service is a
+ *   **singleton**: one shared instance handles all requests.
+ * - When `scope` returns a **truthy string**, the same instance is reused
+ *   for all requests that share that key (e.g. one instance per session).
+ * - When `scope` returns **`null`**, a **fresh instance** is created for
+ *   every request and discarded afterwards (recommended for stateless services).
+ *
+ * @template TInstance - The shape of the service's state object.
+ */
+export interface ServiceDefinition<TInstance extends ServiceInstance = ServiceInstance> {
+    /**
+     * Determine the scope key for the current request.
+     *
+     * - Return a **string** → instances are cached by that key (e.g. session ID).
+     * - Return **`null`**   → create a new, disposable instance per request.
+     * - Omit entirely       → the service is a **singleton** (one global instance).
+     *
+     * @example
+     * ```ts
+     * scope: (req) => (req as any).session?.ssid ?? null,
+     * ```
+     */
+    scope?: (req: RouterRequest) => string | null;
+    /**
+     * Factory that returns the initial state object for a new instance.
+     *
+     * When omitted, the instance is initialised as `{ $key: key }`.
+     *
+     * @param key - The scope key passed by the framework (`'singleton'` for
+     *              global instances, `null` for ephemeral ones, or the string
+     *              returned by `scope()`).
+     */
+    data?: (key: string | null) => TInstance;
+    /**
+     * Lifecycle hook called once after an instance is created and its methods
+     * are mixed in.
+     *
+     * May be synchronous or asynchronous.  When asynchronous, the returned
+     * `Promise` is not awaited by the framework — use a `throwIfNotReady()`
+     * pattern in your methods to guard against premature access.
+     */
+    setup?: (this: TInstance) => void | Promise<void>;
+    /**
+     * Helper methods mixed into every service instance.
+     *
+     * All methods are bound to the instance (`this` = instance), so they can
+     * read and write state, call other methods, and throw {@link ApiError}
+     * objects to trigger HTTP error responses.
+     */
+    methods?: ServiceMethods<TInstance>;
+    /** Route handlers for `GET` requests. */
+    GET?: RouteMap<TInstance>;
+    /** Route handlers for `POST` requests. */
+    POST?: RouteMap<TInstance>;
+    /** Route handlers for `PUT` requests. */
+    PUT?: RouteMap<TInstance>;
+    /** Route handlers for `DELETE` requests. */
+    DELETE?: RouteMap<TInstance>;
+    /** Route handlers for `PATCH` requests. */
+    PATCH?: RouteMap<TInstance>;
+}
+/**
+ * Build an Express-compatible router from a service definition object.
+ *
+ * The returned router is suitable for mounting via `app.use()`:
+ *
+ * ```ts
+ * import myService from './my-service.js';
+ *
+ * app.use('/api', apiBuilder(myService));
+ * ```
+ *
+ * **Route handlers** declared in `service.GET`, `service.POST`, etc. are
+ * called with `this` bound to the service instance.  They receive two
+ * arguments:
+ * 1. `params` — merged route + query-string parameters from `req.params`.
+ * 2. `body`   — the parsed request body from `req.body` (requires a
+ *    body-parsing middleware such as `json()` to run first).
+ *
+ * **Return values:**
+ * - A **truthy value** (or a `Promise` resolving to one) → serialised as JSON
+ *   with status `200 OK`.
+ * - A **falsy value** (`undefined`, `null`, `false`, `0`, `''`) or a
+ *   `Promise` resolving to one → `201 No Content` (useful for mutations).
+ *
+ * **Error handling:**
+ * - Throwing or rejecting with `{ httpStatus, message }` sends the
+ *   corresponding HTTP error.
+ * - Throwing or rejecting with `{ httpStatus, data }` sends the `data` object
+ *   as a JSON body.
+ * - Any other thrown value produces `500 Internal Server Error`.
+ *
+ * @param service - The service definition (see {@link ServiceDefinition}).
+ * @returns A router instance pre-configured with all declared routes.
+ */
+export declare function apiBuilder<TInstance extends ServiceInstance = ServiceInstance>(service: ServiceDefinition<TInstance>): Router;
+export default apiBuilder;
+//# sourceMappingURL=apis.d.ts.map

package/dist/apis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apis.d.ts","sourceRoot":"","sources":["../src/apis.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,aAAa,EAAkB,MAAM,EAAE,MAAM,aAAa,CAAC;AAMzE;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAQ;IACvB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,aAAa,CAAC,SAAS,GAAG,eAAe,IAAI,CACvD,IAAI,EAAI,SAAS,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,IAAI,CAAC,EAAG,OAAO,KACZ,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IACtD,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,cAAc,CAAC,SAAS,SAAS,eAAe,GAAG,eAAe,IAAI;IAChF,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;CAClE,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,QAAQ,CAAC,SAAS,SAAS,eAAe,GAAG,eAAe,IAAI;IAC1E,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;CAC1C,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,iBAAiB,CAAC,SAAS,SAAS,eAAe,GAAG,eAAe;IACpF;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,MAAM,GAAG,IAAI,CAAC;IAE9C;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,SAAS,CAAC;IAEzC;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElD;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;IAEpC,yCAAyC;IACzC,GAAG,CAAC,EAAK,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC7B,0CAA0C;IAC1C,IAAI,CAAC,EAAI,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC7B,yCAAyC;IACzC,GAAG,CAAC,EAAK,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC7B,4CAA4C;IAC5C,MAAM,CAAC,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC7B,2CAA2C;IAC3C,KAAK,CAAC,EAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;CAC9B;AAyID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,UAAU,CAAC,SAAS,SAAS,eAAe,GAAG,eAAe,EAC5E,OAAO,EAAE,iBAAiB,CAAC,SAAS,CAAC,GACpC,MAAM,CAmFR;AAED,eAAe,UAAU,CAAC"}

package/dist/apis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apis.js","sourceRoot":"","sources":["../src/apis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,YAAY,CAAC;;;;;AAgUb,gCAqFC;AAnZD,4DAAuC;AAqJvC,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;;;;;;;;;GAaG;AACH,SAAS,WAAW,CAClB,OAAqC,EACrC,GAAsB;IAEtB,MAAM,QAAQ,GAAc,OAAO,CAAC,IAAI;QACtC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC;QACnB,CAAC,CAAE,EAAE,IAAI,EAAE,GAAG,EAA2B,CAAC;IAE5C,qEAAqE;IACrE,sFAAsF;IACtF,6EAA6E;IAC7E,yEAAyE;IACzE,yEAAyE;IACzE,+EAA+E;IAC/E,+BAA+B;IAC/B,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,KAAK,MAAM,UAAU,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YACtD,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;YAC1C,QAAoC,CAAC,UAAU,CAAC,GAAG,UAElD,GAAG,IAAe;gBAElB,OAAO,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YACtC,CAAC,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,OAAO,CAAC,KAAK;QACf,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAQ,CAAC,CAAC;IAE1C,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAS,eAAe,CACtB,OAAqC,EACrC,OAAkC,EAClC,GAAsB;IAEtB,IAAI,OAAO,OAAO,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;QACxC,+CAA+C;QAC/C,OAAO,OAAO,CAAC,WAAW,CAAC,CAAC;IAC9B,CAAC;IAED,0EAA0E;IAC1E,sEAAsE;IACtE,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAE/B,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACjB,mEAAmE;QACnE,OAAO,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,mDAAmD;IACnD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC;QACf,OAAO,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAE3C,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC;AACtB,CAAC;AAED,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;GAKG;AACH,SAAS,QAAQ,CAAC,GAAmB,EAAE,IAAa;IAClD,uEAAuE;IACvE,yEAAyE;IACzE,sEAAsE;IACtE,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,iCAAiC,CAAC,CAAC;IACjE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,SAAS,CAAC,GAAmB,EAAE,GAAY;IAClD,MAAM,CAAC,GAAG,GAA2B,CAAC;IACtC,MAAM,MAAM,GAAG,CAAC,EAAE,UAAU,IAAI,GAAG,CAAC;IACpC,IAAI,CAAC,EAAE,IAAI,KAAK,SAAS,EAAE,CAAC;QAC1B,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,iCAAiC,CAAC,CAAC;QACjE,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAClD,CAAC;SAAM,CAAC;QACN,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,IAAI,gBAAgB,CAAC,CAAC;IAC1D,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,SAAgB,UAAU,CACxB,OAAqC;IAErC,MAAM,GAAG,GAAO,IAAA,mBAAY,GAAE,CAAC;IAC/B,MAAM,OAAO,GAA8B,EAAE,CAAC;IAE9C,yEAAyE;IACzE,IAAI,OAAO,OAAO,CAAC,KAAK,KAAK,UAAU;QACrC,qEAAqE;QACrE,qEAAqE;QACrE,wDAAwD;QACxD,OAAO,CAAC,WAAW,CAAC,GAAG,WAAW,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IAE3D;;;;;;;;;;;;OAYG;IACH,SAAS,WAAW,CAClB,QAAyC,EACzC,QAA4F;QAE5F,IAAI,CAAC,QAAQ;YAAE,OAAO;QAEtB,sEAAsE;QACtE,wEAAwE;QACxE,uEAAuE;QACvE,uDAAuD;QACvD,gEAAgE;QAChE,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YACtD,MAAM,KAAK,GAAG,CAAC,CAAS,EAAE,EAAE;gBAC1B,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;gBACpD,OAAO,IAAI,CAAC,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,GAAG,EAAE,CAAC;YAC7E,CAAC,CAAC;YACF,OAAO,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;QACnD,CAAC,CAAC,CAAC;QAEH,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;YAC/B,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;YAE9B,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAkB,EAAE,GAAmB,EAAQ,EAAE;gBAC/D,MAAM,MAAM,GAAG,GAAG,CAAC,MAAgC,CAAC;gBACpD,MAAM,IAAI,GAAM,GAAW,CAAC,IAAI,CAAC;gBAEjC,IAAI,CAAC;oBACH,MAAM,QAAQ,GAAG,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;oBACxD,MAAM,GAAG,GAAQ,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;oBAExD,IAAI,GAAG,YAAY,OAAO,EAAE,CAAC;wBAC3B,GAAG;6BACA,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE;4BACZ,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,KAAK,IAAI,GAAG,KAAK,CAAC,IAAI,GAAG,KAAK,EAAE;gCAC/E,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;;gCAEnB,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;wBAC1B,CAAC,CAAC;6BACD,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;oBACzC,CAAC;yBAAM,CAAC;wBACN,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,KAAK,IAAI,GAAG,KAAK,CAAC,IAAI,GAAG,KAAK,EAAE;4BAC/E,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;;4BAEnB,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;oBAC1B,CAAC;gBACH,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;gBACtB,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,WAAW,CAAC,OAAO,CAAC,GAAG,EAAK,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAK,CAAQ,CAAC,CAAC,CAAC;IACrE,WAAW,CAAC,OAAO,CAAC,IAAI,EAAI,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAI,CAAQ,CAAC,CAAC,CAAC;IACrE,WAAW,CAAC,OAAO,CAAC,GAAG,EAAK,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAK,CAAQ,CAAC,CAAC,CAAC;IACrE,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAQ,CAAC,CAAC,CAAC;IACrE,WAAW,CAAC,OAAO,CAAC,KAAK,EAAG,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAG,CAAQ,CAAC,CAAC,CAAC;IAErE,OAAO,GAAG,CAAC;AACb,CAAC;AAED,kBAAe,UAAU,CAAC"}

package/dist/git.d.ts

@@ -0,0 +1,74 @@
+import type { RouterRequest, RouterResponse } from './router.js';
+/**
+ * Configuration options for {@link gitHandler}.
+ */
+export interface GitHandlerOptions {
+    /**
+     * Resolve the absolute filesystem path of the Git repository for an
+     * incoming request.
+     *
+     * Return a non-empty string to serve that repository, or a falsy value
+     * (`''`, `null`, `undefined`) to respond with **404 Repository not found**.
+     *
+     * This is the only required option; all others have defaults.
+     *
+     * @example
+     * ```ts
+     * repository: (req) => path.join('/srv/git', req.params.repo + '.git')
+     * ```
+     */
+    repository: (req: RouterRequest) => string | null | undefined | false;
+    /**
+     * Directory that contains the `git-upload-pack` executable, including a
+     * trailing path separator (e.g. `'/usr/lib/git-core/'`).
+     *
+     * Leave empty (default) to locate the binary via the system `PATH`.
+     */
+    gitPath?: string;
+    /**
+     * When `true`, the `--strict` flag is passed to `git-upload-pack`.
+     * This causes the process to exit with an error when the resolved path is
+     * not a bare Git repository.
+     *
+     * Defaults to `false` (non-strict / `--no-strict`).
+     */
+    strict?: boolean;
+    /**
+     * Kill the `git-upload-pack` process if it does not complete within this
+     * many **seconds**.  When omitted or `0`, no timeout is applied.
+     */
+    timeout?: number | string;
+}
+/**
+ * Middleware factory that exposes a Git repository over the **Git Smart HTTP
+ * protocol** (read-only fetch / clone, via `git-upload-pack`).
+ *
+ * Mount this handler at the root of a repository-scoped path so that the two
+ * sub-paths it handles (`/info/refs` and `/git-upload-pack`) are reachable:
+ *
+ * ```ts
+ * app.use('/repos/:repo', gitHandler({
+ *   repository: (req) => path.join('/srv/git', req.params.repo + '.git'),
+ * }));
+ * ```
+ *
+ * **Supported endpoints:**
+ *
+ * | Method | Path              | Purpose                                      |
+ * |--------|-------------------|----------------------------------------------|
+ * | GET    | `/info/refs`      | Smart HTTP capability advertisement          |
+ * | POST   | `/git-upload-pack`| Pack-file negotiation and transfer           |
+ *
+ * Only `git-upload-pack` (fetch / clone) is implemented.
+ * `git-receive-pack` (push) is intentionally excluded.
+ *
+ * **Compression:** gzip-compressed POST bodies are transparently decompressed
+ * before being piped to `git-upload-pack`.
+ *
+ * @param opt - Handler configuration (see {@link GitHandlerOptions}).
+ * @returns An Express-compatible middleware function `(req, res) => void`.
+ * @throws {TypeError} When `opt.repository` is not a function.
+ */
+export declare function gitHandler(opt: GitHandlerOptions): (req: RouterRequest, res: RouterResponse) => void;
+export default gitHandler;
+//# sourceMappingURL=git.d.ts.map

package/dist/git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAMjE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;;;;OAaG;IACH,UAAU,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,CAAC;IAEtE;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC3B;AA6CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,iBAAiB,GAAG,CAAC,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,cAAc,KAAK,IAAI,CAwIpG;AAyCD,eAAe,UAAU,CAAC"}

package/dist/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @module expediate
+ * TypeScript package for web server routing.
+ */
+import createRouter from './router';
+export { createRouter };
+export type { Router, RouterRequest, RouterResponse, Middleware, MiddlewareArg, NextFunction, Layer, CookieOptions, TlsOptions, StringMap, } from './router';
+export { serveStatic, serveFile, sendFile, mime } from './static';
+export type { StaticOptions, Mime } from './static';
+export { json, formData, parseBody, logger } from './misc';
+export type { BodyOptions, LoggerOptions, FormPart, } from './misc';
+import createJwtPlugin from './jwt-auth';
+export { createJwtPlugin };
+export type { JwtPlugin, JwtConfig } from './jwt-auth';
+import gitHandler from './git';
+export { gitHandler };
+export type { GitHandlerOptions, } from './git';
+import apiBuilder from './apis';
+export { apiBuilder };
+export type { ApiError, ServiceMethod, ServiceInstance, ServiceMethods, RouteMap, ServiceDefinition } from './apis';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoBA;;;GAGG;AAGH,OAAO,YAAY,MAAM,UAAU,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,CAAA;AACvB,YAAY,EACV,MAAM,EACN,aAAa,EACb,cAAc,EACd,UAAU,EACV,aAAa,EACb,YAAY,EACZ,KAAK,EACL,aAAa,EACb,UAAU,EACV,SAAS,GACV,MAAM,UAAU,CAAC;AAIlB,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAClE,YAAY,EACV,aAAa,EACb,IAAI,EACL,MAAM,UAAU,CAAC;AAIlB,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC3D,YAAY,EACV,WAAW,EACX,aAAa,EACb,QAAQ,GACT,MAAM,QAAQ,CAAC;AAGhB,OAAO,eAAe,MAAM,YAAY,CAAA;AACxC,OAAO,EAAE,eAAe,EAAE,CAAA;AAC1B,YAAY,EACV,SAAS,EACT,SAAS,EACV,MAAM,YAAY,CAAC;AAGpB,OAAQ,UAAU,MAAM,OAAO,CAAA;AAC/B,OAAO,EAAE,UAAU,EAAE,CAAA;AACrB,YAAY,EACR,iBAAiB,GACpB,MAAM,OAAO,CAAA;AAGd,OAAO,UAAU,MAAM,QAAQ,CAAA;AAC/B,OAAO,EAAE,UAAU,EAAE,CAAA;AACrB,YAAY,EACR,QAAQ,EACR,aAAa,EACb,eAAe,EACf,cAAc,EACd,QAAQ,EACR,iBAAiB,EACpB,MAAM,QAAQ,CAAA"}

package/dist/index.js

@@ -0,0 +1,55 @@
+"use strict";
+/* Copyright 2021 Fabien Bavent
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a
+ * copy of this software and associated documentation files (the "Software"),
+ * to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+ * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+ */
+/**
+ * @module expediate
+ * TypeScript package for web server routing.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiBuilder = exports.gitHandler = exports.createJwtPlugin = exports.logger = exports.parseBody = exports.formData = exports.json = exports.mime = exports.sendFile = exports.serveFile = exports.serveStatic = exports.createRouter = void 0;
+// ── Router ────────────────────────────────────────────────────────────────────
+const router_1 = __importDefault(require("./router"));
+exports.createRouter = router_1.default;
+// ── Static ────────────────────────────────────────────────────────────────────
+var static_1 = require("./static");
+Object.defineProperty(exports, "serveStatic", { enumerable: true, get: function () { return static_1.serveStatic; } });
+Object.defineProperty(exports, "serveFile", { enumerable: true, get: function () { return static_1.serveFile; } });
+Object.defineProperty(exports, "sendFile", { enumerable: true, get: function () { return static_1.sendFile; } });
+Object.defineProperty(exports, "mime", { enumerable: true, get: function () { return static_1.mime; } });
+// ── Miscallenous ──────────────────────────────────────────────────────────────
+var misc_1 = require("./misc");
+Object.defineProperty(exports, "json", { enumerable: true, get: function () { return misc_1.json; } });
+Object.defineProperty(exports, "formData", { enumerable: true, get: function () { return misc_1.formData; } });
+Object.defineProperty(exports, "parseBody", { enumerable: true, get: function () { return misc_1.parseBody; } });
+Object.defineProperty(exports, "logger", { enumerable: true, get: function () { return misc_1.logger; } });
+// ── JWT Authentication ────────────────────────────────────────────────────────
+const jwt_auth_1 = __importDefault(require("./jwt-auth"));
+exports.createJwtPlugin = jwt_auth_1.default;
+// ── Git repository ────────────────────────────────────────────────────────────
+const git_1 = __importDefault(require("./git"));
+exports.gitHandler = git_1.default;
+// ── API Service ───────────────────────────────────────────────────────────────
+const apis_1 = __importDefault(require("./apis"));
+exports.apiBuilder = apis_1.default;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;;;GAGG;;;;;;AAEH,iFAAiF;AACjF,sDAAoC;AAC3B,uBADF,gBAAY,CACE;AAcrB,iFAAiF;AAEjF,mCAAkE;AAAzD,qGAAA,WAAW,OAAA;AAAE,mGAAA,SAAS,OAAA;AAAE,kGAAA,QAAQ,OAAA;AAAE,8FAAA,IAAI,OAAA;AAM/C,iFAAiF;AAEjF,+BAA2D;AAAlD,4FAAA,IAAI,OAAA;AAAE,gGAAA,QAAQ,OAAA;AAAE,iGAAA,SAAS,OAAA;AAAE,8FAAA,MAAM,OAAA;AAO1C,iFAAiF;AACjF,0DAAwC;AAC/B,0BADF,kBAAe,CACE;AAMxB,iFAAiF;AACjF,gDAA+B;AACtB,qBADD,aAAU,CACC;AAKnB,iFAAiF;AACjF,kDAA+B;AACtB,qBADF,cAAU,CACE"}

package/dist/jwt-auth.d.ts

@@ -0,0 +1,280 @@
+/**
+ * jwt-auth.ts
+ *
+ * JWT authentication plugin for the Expediate router.
+ *
+ * Provides:
+ * - Stateless access tokens (HS256 / HS384 / HS512 HMAC-signed JWTs).
+ * - Opaque refresh tokens with server-side storage and automatic rotation.
+ * - Route handlers for login, token refresh, and logout.
+ * - Middleware for token validation, authorisation, role checks, and
+ *   permission checks.
+ *
+ * Security notes:
+ * - Passwords are hashed with SHA-256 for demonstration purposes only.
+ *   Replace with bcrypt / argon2 in production.
+ * - The default secrets are placeholders — always override them in production.
+ * - Refresh token storage defaults to an in-process Map; replace with a
+ *   persistent store (Redis, database) for multi-instance deployments.
+ */
+import type { Middleware } from './router.js';
+/** A user record as stored in (or returned by) the user database. */
+export interface UserRecord {
+    /** Stable unique identifier (used as JWT `sub` claim when present). */
+    id?: string;
+    /** Login username. */
+    username: string;
+    /**
+     * SHA-256 hex digest of the user's password.
+     * Replace with a bcrypt/argon2 hash in production.
+     */
+    passwordHash: string;
+    /** Role labels assigned to this user (e.g. `'admin'`, `'editor'`). */
+    roles?: string[];
+    /**
+     * Fine-grained permission strings assigned to this user
+     * (e.g. `'read'`, `'write'`, `'delete'`).
+     */
+    permissions?: string[];
+    /** Any additional fields the application wants to carry. */
+    [key: string]: unknown;
+}
+/**
+ * The decoded JWT access-token payload attached to `req.user` after
+ * successful authentication.
+ */
+export interface TokenPayload {
+    /** JWT subject — typically the user's stable ID. */
+    sub: string;
+    /** Username extracted from the user record. */
+    username: string;
+    /** Issuer claim, set to `config.issuer`. */
+    iss: string;
+    /** Issued-at timestamp (Unix seconds). */
+    iat: number;
+    /** Expiration timestamp (Unix seconds). */
+    exp: number;
+    /** Roles copied from the user record. */
+    roles?: string[];
+    /** Permissions copied from the user record. */
+    permissions?: string[];
+    /** Any additional claims produced by `config.payload`. */
+    [key: string]: unknown;
+}
+/** Internal metadata stored alongside each active refresh token. */
+interface RefreshTokenData {
+    /** Username the refresh token was issued to. */
+    username: string;
+    /** Unix ms timestamp of issuance. */
+    issuedAt: number;
+    /** Unix ms timestamp after which the token must be rejected. */
+    expiresAt: number;
+}
+/**
+ * Minimal interface for the refresh-token store.
+ * Any object implementing these four methods is accepted (Map, Redis client
+ * adapter, database wrapper, etc.).
+ */
+export interface TokenStore {
+    set(key: string, value: RefreshTokenData): void;
+    get(key: string): RefreshTokenData | undefined;
+    delete(key: string): void;
+    has(key: string): boolean;
+}
+/**
+ * Supported HMAC-SHA signing algorithms for JWT.
+ * RS*, ES*, and PS* families are not yet implemented.
+ */
+export type JwtAlgorithm = 'HS256' | 'HS384' | 'HS512';
+/**
+ * Full configuration object for {@link createJwtPlugin}.
+ * All fields have defaults; override only what you need.
+ */
+export interface JwtConfig {
+    /** HMAC secret used to sign access tokens. **Change in production.** */
+    accessTokenSecret: string;
+    /** HMAC secret used to sign refresh tokens (currently unused — refresh   *
+     * tokens are opaque random strings, not JWTs). Reserved for future use. */
+    refreshTokenSecret: string;
+    /** Access token lifetime in **seconds**. Defaults to 15 minutes. */
+    accessTokenExpiry: number;
+    /** Refresh token lifetime in **seconds**. Defaults to 7 days. */
+    refreshTokenExpiry: number;
+    /** Value placed in the JWT `iss` claim. */
+    issuer: string;
+    /**
+     * When `true`, the `authenticate` middleware rejects tokens whose `iss`
+     * claim does not match `config.issuer`.
+     * Defaults to `false` (issuer not checked).
+     */
+    checkIssuer: boolean;
+    /** JWT signing algorithm. Defaults to `'HS256'`. */
+    alg: JwtAlgorithm;
+    /**
+     * Extract the login username from a user record.
+     * Defaults to `(user) => user.username`.
+     */
+    username: (user: UserRecord) => string;
+    /**
+     * Fetch a user record by username.
+     * Return `undefined` (or any falsy value) when the user does not exist.
+     */
+    fetchUser: (username: string) => UserRecord | undefined;
+    /**
+     * Return `true` when the supplied plain-text `password` is valid for
+     * `user`, `false` otherwise.
+     *
+     * The default implementation compares SHA-256 hashes; replace with a
+     * timing-safe bcrypt/argon2 check in production.
+     */
+    isPasswordValid: (user: UserRecord, password: string) => boolean;
+    /**
+     * Build the JWT payload for a user.
+     * The `iss`, `iat`, `exp`, and `sub` claims are added automatically.
+     * Returning a partial object is fine — the plugin merges the rest.
+     */
+    payload: (user: UserRecord) => Partial<TokenPayload>;
+    /**
+     * Active refresh-token store.
+     * Defaults to an in-process `Map` (lost on restart; not suitable for
+     * multi-instance deployments).
+     */
+    refreshTokenStore: TokenStore;
+}
+/** Result returned by {@link verifyToken}. */
+type VerifyResult = {
+    valid: true;
+    payload: TokenPayload;
+} | {
+    valid: false;
+    error: string;
+};
+/**
+ * Hash a plain-text password with SHA-256 and return the hex digest.
+ *
+ * > **⚠ Warning:** SHA-256 is fast and therefore unsuitable for password
+ * > hashing in production.  Use bcrypt or argon2 instead.
+ *
+ * @param password - The plain-text password to hash.
+ * @returns A 64-character lowercase hex string.
+ */
+export declare function hashPassword(password: string): string;
+/**
+ * Default in-memory user database used when no custom `fetchUser` is
+ * provided.  Contains three demo accounts: alice (admin), bob (editor),
+ * charlie (viewer).
+ *
+ * Replace or ignore this map entirely when you supply your own `fetchUser`.
+ */
+export declare const userDatabase: Map<string, UserRecord>;
+/**
+ * Sign a payload object and return a compact JWT string.
+ *
+ * Automatically adds the `iat` (issued-at) and `exp` (expiration) claims.
+ * Any claims already present in `payload` are preserved and take precedence
+ * over `iat`/`exp` (use this to override expiry if needed).
+ *
+ * @param payload   - JWT payload claims (must be JSON-serialisable).
+ * @param secret    - HMAC secret used to sign the token.
+ * @param expiresIn - Validity window in **seconds** from the current time.
+ * @param alg       - Signing algorithm. Defaults to `'HS256'`.
+ * @returns A compact JWT string in the form `header.payload.signature`.
+ */
+declare function signToken(payload: Partial<TokenPayload>, secret: string, expiresIn: number, alg?: JwtAlgorithm): string;
+/**
+ * Verify a compact JWT string and return its decoded payload on success.
+ *
+ * Performs the following checks in order:
+ * 1. Structural validity (exactly three dot-separated segments).
+ * 2. Algorithm consistency (header `alg` matches the expected `alg`).
+ * 3. Signature integrity (timing-safe HMAC comparison).
+ * 4. Expiration (`exp` claim is in the future).
+ *
+ * All errors are returned as `{ valid: false, error }` — no exception is
+ * thrown to the caller.
+ *
+ * @param token  - The compact JWT string to verify.
+ * @param secret - HMAC secret that was used to sign the token.
+ * @param alg    - Expected signing algorithm.
+ * @returns A {@link VerifyResult} discriminated union.
+ */
+declare function verifyToken(token: string, secret: string, alg: JwtAlgorithm): VerifyResult;
+/**
+ * The object returned by {@link createJwtPlugin}.
+ *
+ * Mount the handlers on your router and apply the middleware to protected
+ * routes:
+ *
+ * ```ts
+ * const auth = createJwtPlugin({ accessTokenSecret: process.env.JWT_SECRET! });
+ *
+ * app.post('/auth/login',   json(), auth.login);
+ * app.post('/auth/refresh', json(), auth.refresh);
+ * app.post('/auth/logout',  json(), auth.logout);
+ *
+ * app.get('/me',    auth.authenticate, auth.authorize, getProfile);
+ * app.delete('/admin', ...auth.requireRole('admin'), deleteHandler);
+ * app.put('/posts', ...auth.requirePermission('write'), updateHandler);
+ * ```
+ */
+export interface JwtPlugin {
+    /**
+     * Route handler for `POST /auth/login`.
+     * Expects a JSON body with `{ username, password }`.
+     * On success: responds with `{ accessToken, refreshToken, expiresIn, tokenType }`.
+     */
+    login: Middleware;
+    /**
+     * Route handler for `POST /auth/refresh`.
+     * Expects a JSON body with `{ username, refreshToken }`.
+     * On success: responds with a new `{ accessToken, refreshToken, ... }` pair.
+     */
+    refresh: Middleware;
+    /**
+     * Route handler for `POST /auth/logout`.
+     * Expects a JSON body with `{ refreshToken }` (optional).
+     * Always responds with 200; revokes the refresh token if provided.
+     */
+    logout: Middleware;
+    /**
+     * Middleware that validates the `Authorization: Bearer <token>` header.
+     * Sets `req.user` to the decoded {@link TokenPayload} on success.
+     * Calls `next()` silently (without error) when the token is absent or invalid,
+     * allowing the route to decide how to handle unauthenticated requests.
+     */
+    authenticate: Middleware;
+    /**
+     * Middleware that rejects unauthenticated requests with 401.
+     * Should be placed **after** {@link authenticate}:
+     * `router.get('/me', auth.authenticate, auth.authorize, handler)`.
+     */
+    authorize: Middleware;
+    /**
+     * Middleware factory that requires the authenticated user to have at least
+     * one of the specified roles.  Returns `[authenticate, roleCheck]` so it
+     * can be spread directly into a route registration:
+     * `router.get('/admin', ...auth.requireRole('admin'), handler)`.
+     * Responds with 401 when unauthenticated, 403 when the role is missing.
+     */
+    requireRole: (...roles: string[]) => Middleware[];
+    /**
+     * Middleware factory that requires the authenticated user to have **all**
+     * of the specified permissions.  Returns `[authenticate, permCheck]`.
+     * Responds with 401 when unauthenticated, 403 when any permission is missing.
+     */
+    requirePermission: (...permissions: string[]) => Middleware[];
+}
+/**
+ * Create a JWT authentication plugin pre-configured with the given options.
+ *
+ * All config fields have safe defaults for development.  At minimum, set
+ * `accessTokenSecret` (and `refreshTokenSecret` if you plan to use it) to
+ * random values in production.
+ *
+ * @param userConfig - Partial {@link JwtConfig} overrides.
+ * @returns A {@link JwtPlugin} object exposing handlers and middleware.
+ */
+export declare function createJwtPlugin(userConfig?: Partial<JwtConfig>): JwtPlugin;
+export default createJwtPlugin;
+export { signToken, verifyToken, hashPassword as _hashPassword };
+//# sourceMappingURL=jwt-auth.d.ts.map

package/dist/jwt-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt-auth.d.ts","sourceRoot":"","sources":["../src/jwt-auth.ts"],"names":[],"mappings":"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"}