expediate 0.0.3 → 1.0.0

package/dist/router.d.ts

@@ -0,0 +1,224 @@
+import * as http from 'http';
+/** A key-value map of arbitrary string values. */
+type StringMap = Record<string, string>;
+/**
+ * Extended HTTP incoming message that carries parsed routing metadata.
+ * Augments the standard `http.IncomingMessage` with fields populated by
+ * the router before any middleware is invoked.
+ */
+interface RouterRequest extends http.IncomingMessage {
+    /** The original, unmodified URL string from the HTTP request. */
+    originalUrl: string;
+    /**
+     * The current path being matched. Prefix-style layers (`use`)
+     * rewrite this field after matching so that nested routers only see the
+     * remaining suffix. Exact-method layers (`all`, `get`, `post`, etc.) leave it
+     * untouched so that chained middlewares sharing the same path each match.
+     */
+    path: string;
+    /**
+     * Aggregated parameters from all sources.
+     * URL query parameters are merged first; named route parameters (from both
+     * plain-string and RegExp patterns) override them when a route matches.
+     */
+    params: StringMap;
+    /**
+     * Structured query buckets:
+     * - `url`   — parameters parsed from the query string.
+     * - `route` — named parameters captured from the route pattern.
+     */
+    queries: {
+        url?: StringMap;
+        route?: StringMap;
+    };
+    /** Parsed cookies sent with the request. */
+    cookies: StringMap;
+}
+/**
+ * Extended HTTP server response with convenience helpers.
+ * Augments the standard `http.ServerResponse`.
+ */
+interface RouterResponse extends http.ServerResponse {
+    /**
+     * Write `data` (if provided) and end the response.
+     * Equivalent to `res.write(data); res.end()`.
+     */
+    send(data?: string): void;
+    /**
+     * Set the HTTP status code and optional response headers, then return
+     * `this` so calls can be chained (e.g. `res.status(404).end(...)`).
+     */
+    status(code: number, headers?: StringMap): this;
+    /** Redirect the client to `url` with a 302 Found response. */
+    redirect(url: string): void;
+    /**
+     * Append a `Set-Cookie` header for the given `name`/`value` pair.
+     * Returns `this` to allow chaining.
+     */
+    cookie(name: string, value: string | object, options?: CookieOptions): this;
+}
+/** Options accepted by `res.cookie()`. */
+interface CookieOptions {
+    /** Sign the cookie value (requires a secret on the request). */
+    signed?: boolean;
+    /** Expiry date for the cookie. */
+    expires?: Date;
+    /** Max age in milliseconds; converted to seconds in the `Set-Cookie` header. */
+    maxAge?: number;
+    /** Cookie path (defaults to `'/'`). */
+    path?: string;
+}
+/** Options for HTTPS servers passed to `router.listen()`. */
+interface TlsOptions {
+    key: string | Buffer;
+    cert: string | Buffer;
+    [key: string]: unknown;
+}
+/**
+ * A middleware function. Receives the current request and response objects
+ * and a `next` callback to hand control to the next registered middleware.
+ */
+type Middleware = (req: RouterRequest, res: RouterResponse, next: NextFunction) => void;
+/** Callback used to pass control to the next matching middleware. */
+type NextFunction = () => void;
+/**
+ * A value that can be registered as a route handler: a single `Middleware`
+ * function, a `Router` instance (whose `listener` will be used), or an array
+ * of either. Arrays may not be nested.
+ */
+type MiddlewareArg = Middleware | Router | (Middleware | Router)[];
+/**
+ * Internal representation of a single registered route.
+ * One layer is created per middleware function for every `router.get(...)` /
+ * `router.use(...)` etc. call, and stored in the route table.
+ */
+interface Layer {
+    /** HTTP method this layer is restricted to, or `null` for any method. */
+    method: string | null;
+    /** The original path pattern supplied by the caller. */
+    path: string | RegExp;
+    /**
+     * The compiled `RegExp` used for matching, regardless of whether the
+     * original `path` was a plain string, a glob, or already a `RegExp`.
+     *
+     * - Plain strings (e.g. `'/users/:id'`) are compiled with named capture
+     *   groups so that `:id` becomes `(?<id>[^/]+)`.
+     * - Glob strings (e.g. `'/**\/*.php'`) are compiled following `.gitignore`
+     *   wildcard rules.
+     * - `RegExp` values are stored as-is; named groups are surfaced directly
+     *   as route parameters.
+     */
+    regex: RegExp;
+    /**
+     * When `true`, the portion of `req.path` consumed by `layer.regex` is
+     * stripped before invoking the middleware, exposing only the remaining
+     * suffix to nested routers.
+     *
+     * Set to `true` for prefix-style registrations (`use`) and
+     * `false` for exact-method routes (`all`, `get`, `post`, etc.). Stripping on
+     * exact-match routes would break chained middlewares sharing the same path,
+     * because each subsequent layer would see a truncated path that no longer
+     * matches its own pattern.
+     */
+    stripPath: boolean;
+    /** The middleware function to invoke when the layer matches. */
+    middleware: Middleware;
+}
+/**
+ * The public interface of the object returned by `createRouter()`.
+ *
+ * All route-registration methods share the same uniform signature: a mandatory
+ * `path` argument followed by any number of `MiddlewareArg` values.
+ * A `MiddlewareArg` may be a `Middleware` function, a `Router` instance
+ * (whose `listener` is used automatically), or an array of either.
+ */
+interface Router {
+    /**
+     * Register middleware for all HTTP methods, scoped to `path`.
+     * The matched path prefix is stripped from `req.path` before the middleware
+     * is invoked, so nested routers only see the remaining suffix.
+     * Equivalent to Express's `app.use()`.
+     */
+    use(path: string | RegExp, ...args: MiddlewareArg[]): void;
+    /**
+     * Register middleware for all HTTP methods.
+     * Unlike `use`, it doesn't strips the matched prefix from `req.path`.
+     */
+    all(path: string | RegExp, ...args: MiddlewareArg[]): void;
+    /** Register middleware for `GET` requests. */
+    get(path: string | RegExp, ...args: MiddlewareArg[]): void;
+    /** Register middleware for `PUT` requests. */
+    put(path: string | RegExp, ...args: MiddlewareArg[]): void;
+    /** Register middleware for `POST` requests. */
+    post(path: string | RegExp, ...args: MiddlewareArg[]): void;
+    /** Register middleware for `DELETE` requests. */
+    delete(path: string | RegExp, ...args: MiddlewareArg[]): void;
+    /** Register middleware for `PATCH` requests. */
+    patch(path: string | RegExp, ...args: MiddlewareArg[]): void;
+    /**
+     * Start listening on the given port.
+     * When `opts` contains both `key` and `cert`, an HTTPS server is created;
+     * otherwise a plain HTTP server is used.
+     */
+    listen(port: number, opts?: TlsOptions | (() => void), cb?: () => void): void;
+    /**
+     * The underlying `(req, res, next)` function, allowing this router to be
+     * mounted as middleware inside another router:
+     * `parent.use('/api', child)`.
+     */
+    readonly listener: Middleware;
+}
+/**
+ * Create and return a new `Router` instance.
+ *
+ * The returned object exposes an Express-compatible routing API and doubles
+ * as a middleware function itself (via `router.listener`), so it can be
+ * mounted inside another router:
+ * ```ts
+ * parent.use('/api', child);
+ * ```
+ *
+ * **Path patterns** accepted by all route-registration methods:
+ * - Plain strings with optional `:name` segments — e.g. `'/users/:id'`.
+ *   Each `:name` is compiled to a named capture group and exposed in
+ *   `req.params` on a match.
+ * - Glob strings following `.gitignore` rules — e.g. `'/**\/*.php'`.
+ *   Supported wildcards: `?` (one non-slash char), `*` (any non-slash chars),
+ *   `**` (any chars, including slashes).
+ * - `RegExp` objects — used directly; named groups become route parameters.
+ *
+ * **Middleware arguments** accept any number of variadic `MiddlewareArg`
+ * values, each of which may be:
+ * - A `Middleware` function.
+ * - A `Router` instance (its `listener` is registered automatically).
+ * - An array of either of the above.
+ *
+ * **Path stripping behaviour:**
+ * - `use` — strip the matched path prefix from `req.path` before
+ *   invoking middleware. Nested routers therefore only see the remaining suffix.
+ * - `all` / `get` / `post` / `put` / `delete` / `patch` — leave `req.path` intact
+ *   so that multiple middlewares registered for the same exact path can each
+ *   match and be invoked in sequence via `next()`.
+ *
+ * @returns A fully initialised `Router` ready to register routes and
+ *          optionally start an HTTP or HTTPS server.
+ *
+ * @example
+ * ```ts
+ * const auth = createRouter();
+ * auth.post('/login',  handleLogin);
+ * auth.post('/logout', handleLogout);
+ *
+ * const app = createRouter();
+ * app.use('/auth', auth);                              // mount a sub-router
+ * app.get('/users/:id', requireAuth, getUser);         // multiple middleware
+ * app.get('/**\/*.php', (req, res) =>                 // glob pattern
+ *   res.status(403).send('Forbidden'));
+ *
+ * app.listen(3000, () => console.log('Listening on :3000'));
+ * ```
+ */
+declare function createRouter(): Router;
+export default createRouter;
+export type { Router, RouterRequest, RouterResponse, Middleware, MiddlewareArg, NextFunction, Layer, CookieOptions, TlsOptions, StringMap, };
+//# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

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