@ambarltd/core 0.1.17

package/dist/router.d.ts

@@ -0,0 +1,117 @@
+import * as express from "express";
+import { Future } from "./future";
+type Json = null | string | number | boolean | JsonArray | JsonObject;
+type JsonObject = {
+    [x: string]: Json;
+};
+type JsonArray = Array<Json>;
+/**
+ * A library for making express.js routes pure.
+ *
+ * It's a simple idea. A route handler is a function that takes a request
+ * and a request environment and returns a response.
+ *
+ * ```ts
+ * function myHandler(req: Request, env: T): Promise<Response>
+ * ```
+ *
+ * As you can see, the environment can be any type specified by the handler.
+ * This will allow for type-safe middlewares as the compiler will ensure that
+ * we do not use handlers with invalid environments.
+ * Things like session information should live in the environment.
+ *
+ * Middlewares are functions that take a request and an environment and
+ * return a different environment.
+ *
+ * ```ts
+ * function myMiddleware(req: Request, env: T1): Promise<MiddlewareResponse<T2>>
+ * ```
+ *
+ * This is how you 'modify' an environment. There is no real modification because
+ * everything should be immutable.
+ *
+ * A route is a request handler that returns a success response
+ * or a failure response.
+ */
+type Route<T> = (req: express.Request, env: T) => Future<Response, Response>;
+/**
+ * We use express.js objects for the request, but we will not mutate them.
+ * Instead we will add things to the environment, which is passed alongside
+ * the request.
+ */
+type Request = express.Request;
+type Headers = Record<string, string>;
+declare class JSON {
+    values: {
+        status: number;
+        headers: Headers;
+        content: Json;
+    };
+    constructor(values: {
+        status: number;
+        headers: Headers;
+        content: Json;
+    });
+}
+declare class Redirect {
+    values: {
+        path: string;
+    };
+    constructor(values: {
+        path: string;
+    });
+}
+declare class Render {
+    values: {
+        status: number;
+        headers: Headers;
+        content: string | Json;
+    };
+    constructor(values: {
+        status: number;
+        headers: Headers;
+        content: string | Json;
+    });
+}
+/**
+ * Server-Sent Events response for real-time streaming to clients.
+ * Keeps connection alive and allows server to push updates continuously.
+ */
+declare class SSE {
+    values: {
+        headers: Headers;
+        stream: (emit: SendMessage, onError: OnError) => Future<Error, null>;
+    };
+    constructor(values: {
+        headers: Headers;
+        stream: (emit: SendMessage, onError: OnError) => Future<Error, null>;
+    });
+}
+type SendMessage = (json: Json) => boolean;
+type OnError = (handler: (err: Error) => void) => void;
+type Response = Render | JSON | Redirect | SSE;
+declare const json: ({ status, headers, content, }: {
+    status?: number;
+    headers?: Headers;
+    content: Json;
+}) => Response;
+declare const redirect: (path: string) => Response;
+declare const render: ({ status, headers, content, }: {
+    status?: number;
+    headers?: Headers;
+    content: string | Json;
+}) => Response;
+declare const sse: ({ headers, stream, }: {
+    headers?: Headers;
+    stream: (emit: SendMessage, onError: OnError) => Future<Error, null>;
+}) => Response;
+/** A middleware is something that transforms the environment. */
+type Middleware<A, B> = (req: express.Request, env: A) => Future<Response, B>;
+declare function middleware<A, B>(fun: Middleware<A, B>, route: Route<B>): Route<A>;
+/**
+ * Create an express route handler from a Route.
+ * It expects the route environment to be null because the
+ * environment will ultimately be enriched through middlewares.
+ */
+declare function route(routeHandler: Route<{}>): express.Handler;
+export { type Response, type Request, route, middleware, redirect, render, json, sse, type JSON, type SSE, type SendMessage, type OnError, };

package/dist/router.js

@@ -0,0 +1,106 @@
+class JSON {
+    values;
+    constructor(values) {
+        this.values = values;
+    }
+}
+class Redirect {
+    values;
+    constructor(values) {
+        this.values = values;
+    }
+}
+class Render {
+    values;
+    constructor(values) {
+        this.values = values;
+    }
+}
+/**
+ * Server-Sent Events response for real-time streaming to clients.
+ * Keeps connection alive and allows server to push updates continuously.
+ */
+class SSE {
+    values;
+    constructor(values) {
+        this.values = values;
+    }
+}
+// Convenience constructors for responses.
+const json = ({ status = 200, headers = {}, content, }) => new JSON({ status, headers, content });
+const redirect = (path) => new Redirect({ path });
+const render = ({ status = 200, headers = {}, content, }) => new Render({ status, headers, content });
+const sse = ({ headers = {}, stream, }) => new SSE({ headers, stream });
+function middleware(fun, route) {
+    return (req, env) => fun(req, env).chain(res => route(req, res));
+}
+function send(response, res) {
+    switch (true) {
+        case response instanceof JSON:
+            res.status(response.values.status);
+            res.set(response.values.headers);
+            res.json(response.values.content);
+            return;
+        case response instanceof Render:
+            res.status(response.values.status);
+            res.set(response.values.headers);
+            res.send(response.values.content);
+            return;
+        case response instanceof Redirect:
+            return res.redirect(response.values.path);
+        case response instanceof SSE: {
+            res.set({
+                ...response.values.headers,
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                Connection: "keep-alive",
+            });
+            res.flushHeaders();
+            streamSSEResponse(res, response.values.stream);
+            return;
+        }
+    }
+}
+function streamSSEResponse(res, stream) {
+    let connectionClosed = false;
+    let endStream = () => { };
+    const closeConnection = () => {
+        if (connectionClosed)
+            return;
+        connectionClosed = true;
+        endStream();
+        res.end();
+    };
+    const errorHandlers = [];
+    const handleError = (err) => {
+        if (connectionClosed)
+            return;
+        errorHandlers.forEach(handler => handler(err));
+        closeConnection();
+    };
+    res.on("close", closeConnection);
+    res.on("error", handleError);
+    // start streaming
+    endStream = stream(function emit(payload) {
+        if (connectionClosed)
+            return false;
+        res.write(`data: ${globalThis.JSON.stringify(payload)}\n\n`);
+        return true;
+    }, function onError(handler) {
+        errorHandlers.push(handler);
+    }).fork(handleError, closeConnection);
+}
+function sendResponse(routeHandler, req, res) {
+    routeHandler(req, {}).fork(r => send(r, res), r => send(r, res));
+}
+/**
+ * Create an express route handler from a Route.
+ * It expects the route environment to be null because the
+ * environment will ultimately be enriched through middlewares.
+ */
+function route(routeHandler) {
+    return (req, res) => sendResponse(routeHandler, req, res);
+}
+export { route, middleware, 
+// responses
+redirect, render, json, sse, };

package/dist/test.d.ts

@@ -0,0 +1,63 @@
+export { run, expect, group, test, parseArgs, type RunOptions };
+declare class Test {
+    readonly name: string;
+    readonly fun: () => void | Promise<void>;
+    readonly id: string;
+    constructor(name: string, fun: () => void | Promise<void>);
+}
+declare class Group {
+    readonly name: string;
+    readonly entries: Array<Group | Test>;
+    constructor(name: string, entries: Array<Group | Test>);
+}
+declare const test: (x: string, y: () => void | Promise<void>) => Test;
+declare const group: (x: string, y: Array<Group | Test>) => Group;
+type RunOptions = {
+    filters: ReadonlyArray<RegExp>;
+};
+/**
+ * Run a test suite. This should be the entry point of a test program.
+ *
+ * A sane, simple testing framework. Instead of a complicated test setup which
+ * finds and compiles files, we do the simplest obvious thing: a function that
+ * takes a list of tests. To run the tests execute a Node.js program that calls
+ * this `run` function.
+ *
+ * ```ts
+ * import { run, test, group, expect, parseArgs } from "@ambarltd/core/test";
+ *
+ * run(parseArgs(), [
+ *   group("trivial tests", [
+ *     test("referential equality", () => expect.equals(1, 3)),
+ *     test("structural equality", () => expect.json_equals({}, {})),
+ *     test("async test", async () => {
+ *       const n = await fetchNumberFromTheInternet();
+ *       expect.equals(1, n);
+ *     }),
+ *   ]),
+ * ]);
+ * ```
+ *
+ * If you want tests in different files, just import them like you would
+ * in a normal program.
+ *
+ * ```ts
+ * import { run } from "@ambarltd/core/test";
+ * import * as unit from "@test/unitTests";
+ * import * as integration from "@test/integrationTests";
+ *
+ * run(parseArgs(), [unit.tests, integration.tests]);
+ * ```
+ */
+declare function run(options: RunOptions, groups: Array<Group>): Promise<void>;
+declare const expect: {
+    fail: (reason: string) => void;
+    equals: <T>(a: T, b: T, label?: string) => void;
+    deep_equals: <T>(ra: T, rb: T) => void;
+    greater_than: <T>(a: T, b: T) => void;
+    not_equals: <T>(a: T, b: T) => void;
+    json_equals: <T>(a: T, b: T) => void;
+    contains: (needle: string, haystack: string) => void;
+    throws: (f: () => unknown, g: (e: Error) => void) => void;
+};
+declare function parseArgs(argv?: Array<string>): RunOptions;