expediate 0.0.3 → 1.0.0

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

@@ -0,0 +1,250 @@
+/* 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.
+ */
+'use strict';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiBuilder = apiBuilder;
+const router_js_1 = __importDefault(require("./router.js"));
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Instantiate a new service module for the given scope `key`.
+ *
+ * The lifecycle is:
+ * 1. **`data(key)`** — create the initial state object (or use `{ $key: key }`
+ *    when `data` is not defined).
+ * 2. **Mix in methods** — each entry in `service.methods` is copied onto the
+ *    instance as a regular function bound to `this`.
+ * 3. **`setup()`** — called once on the new instance; may be async.
+ *
+ * @param service - The service definition.
+ * @param key     - The scope key (`'singleton'`, `null`, or a session ID).
+ * @returns A fully initialised service instance.
+ */
+function buildModule(service, key) {
+    const instance = service.data
+        ? service.data(key)
+        : { $key: key };
+    // Mix service methods into the instance, bound to `this = instance`.
+    // BUG FIX: the original used arrow functions `() => method.apply(module, arguments)`.
+    // Arrow functions do NOT have their own `arguments` object — they inherit it
+    // from the enclosing `buildModule` scope (which holds `(service, key)`).
+    // Any arguments forwarded to the method were therefore silently dropped.
+    // Corrected to a regular function expression that captures its own `arguments`
+    // via a rest parameter spread.
+    if (service.methods) {
+        for (const methodName of Object.keys(service.methods)) {
+            const method = service.methods[methodName];
+            instance[methodName] = function (...args) {
+                return method.apply(instance, args);
+            };
+        }
+    }
+    if (service.setup)
+        service.setup.apply(instance, []);
+    return instance;
+}
+/**
+ * Resolve the correct service instance for an incoming request.
+ *
+ * Instance lifecycle by scope:
+ * - **Singleton** (`scope` absent): always returns `modules['singleton']`.
+ * - **Keyed** (`scope` returns a string): look up `modules[key]`; create and
+ *   cache a new instance on first access.
+ * - **Ephemeral** (`scope` returns `null`): create a fresh instance every time;
+ *   never cached.
+ *
+ * @param service - The service definition.
+ * @param modules - The instance cache (mutated when a new keyed instance is created).
+ * @param req     - The incoming request.
+ * @returns The service instance to use for this request.
+ */
+function resolveInstance(service, modules, req) {
+    if (typeof service.scope !== 'function') {
+        // Singleton — always the same global instance.
+        return modules['singleton'];
+    }
+    // BUG FIX: the original called `service.key(req)` which does not exist on
+    // the service definition. The correct method is `service.scope(req)`.
+    const key = service.scope(req);
+    if (key === null) {
+        // Ephemeral — create a fresh, uncached instance for every request.
+        return buildModule(service, null);
+    }
+    // Keyed — retrieve from cache or create and store.
+    if (!modules[key])
+        modules[key] = buildModule(service, key);
+    return modules[key];
+}
+// ---------------------------------------------------------------------------
+// Response helpers
+// ---------------------------------------------------------------------------
+/**
+ * Send a JSON response with the appropriate `Content-Type` header.
+ *
+ * @param res  - The outgoing response.
+ * @param data - Any JSON-serialisable value.
+ */
+function sendJson(res, data) {
+    // BUG FIX: the original called `res.send(JSON.stringify(val))` without
+    // setting a `Content-Type` header. Clients had no way to detect that the
+    // response body was JSON. Corrected by setting the header explicitly.
+    res.setHeader('Content-Type', 'application/json; charset=utf-8');
+    res.send(JSON.stringify(data));
+}
+/**
+ * Translate a caught error (thrown or rejected by a service method) into an
+ * HTTP error response.
+ *
+ * Expected shape: `{ httpStatus?, data?, message? }` (see {@link ApiError}).
+ * Any other thrown value is treated as an opaque 500 Internal Server Error.
+ *
+ * @param res - The outgoing response.
+ * @param err - The caught value.
+ */
+function sendError(res, err) {
+    const e = err;
+    const status = e?.httpStatus ?? 500;
+    if (e?.data !== undefined) {
+        res.setHeader('Content-Type', 'application/json; charset=utf-8');
+        res.status(status).send(JSON.stringify(e.data));
+    }
+    else {
+        res.status(status).send(e?.message ?? 'Internal error');
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * 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.
+ */
+function apiBuilder(service) {
+    const api = (0, router_js_1.default)();
+    const modules = {};
+    // Pre-build the singleton instance eagerly so `setup()` runs at startup.
+    if (typeof service.scope !== 'function')
+        // BUG FIX: the original called `buildModule(service)` without a key,
+        // passing `undefined` to `data()` and leaving `$key` as `undefined`.
+        // Corrected to pass `'singleton'` as the canonical key.
+        modules['singleton'] = buildModule(service, 'singleton');
+    /**
+     * Register all route handlers from a route map for a given HTTP method.
+     *
+     * Each handler:
+     * 1. Resolves the correct service instance (singleton / keyed / ephemeral).
+     * 2. Invokes the service method with `(params, body)`.
+     * 3. Sends the return value as JSON (or 201 if falsy).
+     * 4. Catches thrown / rejected {@link ApiError} objects and translates them
+     *    into the appropriate HTTP error response.
+     *
+     * @param routeMap - Map of path patterns to service methods (`undefined` = skip).
+     * @param register - Registers a handler on the router for the current HTTP method.
+     */
+    function buildRoutes(routeMap, register) {
+        if (!routeMap)
+            return;
+        // Sort routes by decreasing specificity so that more precise patterns
+        // (more segments, fewer parameters) are registered first in the router.
+        // Without this, a plain path like '/items' would match '/items/1' as a
+        // prefix and steal requests intended for '/items/:id'.
+        // Specificity = (segment count * 100) - (parameter count * 10).
+        const sortedPaths = Object.keys(routeMap).sort((a, b) => {
+            const score = (p) => {
+                const segs = p.split('/').filter(s => s.length > 0);
+                return segs.length * 100 - segs.filter(s => s.startsWith(':')).length * 10;
+            };
+            return score(b) - score(a) || b.localeCompare(a);
+        });
+        for (const path of sortedPaths) {
+            const method = routeMap[path];
+            register(path, (req, res) => {
+                const params = req.params;
+                const body = req.body;
+                try {
+                    const instance = resolveInstance(service, modules, req);
+                    const ret = method.apply(instance, [params, body]);
+                    if (ret instanceof Promise) {
+                        ret
+                            .then((val) => {
+                            if (val !== undefined && val !== null && val !== false && val !== 0 && val !== '')
+                                sendJson(res, val);
+                            else
+                                res.status(201).end();
+                        })
+                            .catch((err) => sendError(res, err));
+                    }
+                    else {
+                        if (ret !== undefined && ret !== null && ret !== false && ret !== 0 && ret !== '')
+                            sendJson(res, ret);
+                        else
+                            res.status(201).end();
+                    }
+                }
+                catch (err) {
+                    sendError(res, err);
+                }
+            });
+        }
+    }
+    buildRoutes(service.GET, (path, h) => api.get(path, h));
+    buildRoutes(service.POST, (path, h) => api.post(path, h));
+    buildRoutes(service.PUT, (path, h) => api.put(path, h));
+    buildRoutes(service.DELETE, (path, h) => api.delete(path, h));
+    buildRoutes(service.PATCH, (path, h) => api.patch(path, h));
+    return api;
+}
+exports.default = apiBuilder;
+//# sourceMappingURL=apis.js.map

package/dist/apis.js.map

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

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"}