@spirobel/mininext 0.2.0 → 0.2.2

package/dist/html.d.ts

@@ -0,0 +1,55 @@
+import type { HandlerReturnType, HtmlHandler, LazyHandlerReturnType, Mini } from "./url";
+export type HtmlStringValues<T = undefined> = HtmlString | HtmlString[] | string | number | HtmlHandler<T> | JsonString | LazyHandlerReturnType | undefined;
+export type JsonStringValues<T = undefined> = HtmlStringValues<T> | {
+    [key: string]: any;
+};
+export declare class HtmlString extends Array {
+    /**
+     * a HtmlString is by default resolved.
+     * if we we pass a function as a value to the html`` template string, it will be unresolved.
+     */
+    resolved: boolean;
+    resolve<T>(mini: Mini<T>): Promise<this>;
+    flat(depth?: number): this;
+}
+export declare function html<X = undefined>(strings: TemplateStringsArray, ...values: HtmlStringValues<X>[]): HtmlString;
+export declare class JsonString extends HtmlString {
+}
+export declare class DangerJsonInHtml extends HtmlString {
+}
+export declare const json: <X = undefined>(strings: TemplateStringsArray, ...values: JsonStringValues<X>[]) => JsonString;
+export declare const dangerjson: <X = undefined>(strings: TemplateStringsArray, ...values: JsonStringValues<X>[]) => DangerJsonInHtml;
+/**
+ * Set the default head for all pages. Can still be overwritten on a per page basis
+ * @param defaultHead - HtmlString
+ *
+ * @example Here is what a default head might look like:
+ *  ```ts
+ *head(html` <title>hello hello</title> `);
+ * url.set([
+ * ["/", (mini) => mini.html`<h1>Hello world</h1>`],
+ *  [
+ *   "/bye",
+ *   (mini) =>
+ *     mini.html`<h1>Goodbye world</h1>${mini.head(
+ *       mini.html` <title>bye bye</title>`
+ *     )}`,
+ *  ],
+ * ]);
+ *  ```
+ */
+export declare function head(defaultHead: HtmlString): void;
+export declare function htmlResponder(mini: Mini, maybeUnresolved: HandlerReturnType, head?: HtmlString, options?: ResponseInit): Promise<Response>;
+/**
+ * Generic html error type guard
+ * @param submissionResult output of some function
+ * @returns boolean - true if the given object has a property called "error" and its value is an instance of HtmlString
+ */
+export declare function isError(submissionResult: any | {
+    error: HtmlString;
+}): submissionResult is {
+    error: HtmlString;
+};
+declare global {
+    var Reloader: HtmlString | undefined;
+}

package/dist/html.js

@@ -0,0 +1,201 @@
+export class HtmlString extends Array {
+    /**
+     * a HtmlString is by default resolved.
+     * if we we pass a function as a value to the html`` template string, it will be unresolved.
+     */
+    resolved = true;
+    async resolve(mini) {
+        if (this.resolved)
+            return this;
+        for (const [index, htmlPiece] of this.entries()) {
+            if (typeof htmlPiece === "function") {
+                let resolvedHtmlPiece = await htmlPiece(mini); //passing mini
+                if (resolvedHtmlPiece instanceof HtmlString) {
+                    resolvedHtmlPiece = await resolvedHtmlPiece.resolve(mini);
+                }
+                // Replace the function with the resolved HTML piece in place
+                this[index] = resolvedHtmlPiece;
+            }
+        }
+        this.resolved = true;
+        return this;
+    }
+    flat(depth = 1) {
+        const flattened = super.flat(depth);
+        const newHtmlString = new this.constructor(...flattened);
+        newHtmlString.resolved = this.resolved;
+        return newHtmlString;
+    }
+}
+export function html(strings, ...values) {
+    const htmlStringArray = new HtmlString();
+    htmlStringArray.resolved = true;
+    // Iterate over strings and values, alternating between them
+    for (const [index, string] of strings.entries()) {
+        htmlStringArray.push(string);
+        if (index < values.length) {
+            const value = values[index];
+            // we can pass arrays of HtmlString and they will get flattened automatically
+            if (Array.isArray(value) &&
+                value.every((val) => val instanceof HtmlString)) {
+                // If the value is an array of HtmlString objects, add the whole array as a single value
+                values[index] = value;
+            }
+            else if (typeof value === "function") {
+                htmlStringArray.resolved = false;
+                values[index] = value;
+            }
+            else if (value instanceof JsonString) {
+                values[index] = html `<div style="color:red;">
+          Please use dangerjson to include json in html. Untrusted input needs
+          to pass through a html template function to get escaped. You can do
+          html -> dangerjson -> html if you want!
+        </div>`;
+            }
+            else if (!(value instanceof HtmlString)) {
+                const notEmpty = value || "";
+                // values will be escaped by default
+                values[index] = Bun.escapeHTML(notEmpty + "");
+            }
+            htmlStringArray.push(values[index]);
+        }
+    }
+    // Flatten the HtmlString array to ensure all nested arrays are properly included
+    return htmlStringArray.flat();
+}
+export class JsonString extends HtmlString {
+}
+export class DangerJsonInHtml extends HtmlString {
+}
+function JsonTemplateProcessor(danger = false) {
+    const constructorr = danger
+        ? () => new DangerJsonInHtml()
+        : () => new JsonString();
+    return function (strings, ...values) {
+        const jsonStringArray = constructorr();
+        jsonStringArray.resolved = true;
+        // Iterate over strings and values, alternating between them
+        for (const [index, string] of strings.entries()) {
+            jsonStringArray.push(string);
+            if (index < values.length) {
+                const value = values[index];
+                // we can pass arrays of HtmlString and they will get flattened automatically
+                if (Array.isArray(value) &&
+                    value.every((val) => val instanceof HtmlString)) {
+                    // If the value is an array of HtmlString objects, add the whole array as a single value
+                    values[index] = value;
+                }
+                else if (typeof value === "function") {
+                    jsonStringArray.resolved = false;
+                    values[index] = value;
+                }
+                else if (!(value instanceof JsonString)) {
+                    const notEmpty = value || "";
+                    // values will be turned into a JSON string
+                    values[index] = JSON.stringify(notEmpty);
+                }
+                jsonStringArray.push(values[index]);
+            }
+        }
+        // Flatten the HtmlString array to ensure all nested arrays are properly included
+        return jsonStringArray.flat();
+    };
+}
+export const json = JsonTemplateProcessor();
+export const dangerjson = JsonTemplateProcessor(true);
+let default_head = html ` <title>mini-next</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <style>
+    /* CSS Reset */
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+
+    /* Set the background color to black */
+    html,
+    body {
+      background-color: #000;
+      color: #fff; /* Set the default text color to white for better contrast */
+    }
+  </style>
+  <script>
+    /* prevent form resubmission */
+    if (window.history.replaceState) {
+      window.history.replaceState(null, null, window.location.href);
+    }
+  </script>`;
+/**
+ * Set the default head for all pages. Can still be overwritten on a per page basis
+ * @param defaultHead - HtmlString
+ *
+ * @example Here is what a default head might look like:
+ *  ```ts
+ *head(html` <title>hello hello</title> `);
+ * url.set([
+ * ["/", (mini) => mini.html`<h1>Hello world</h1>`],
+ *  [
+ *   "/bye",
+ *   (mini) =>
+ *     mini.html`<h1>Goodbye world</h1>${mini.head(
+ *       mini.html` <title>bye bye</title>`
+ *     )}`,
+ *  ],
+ * ]);
+ *  ```
+ */
+export function head(defaultHead) {
+    default_head = defaultHead;
+}
+export async function htmlResponder(mini, maybeUnresolved, head = default_head, options = {
+    headers: {
+        "Content-Type": "text/html; charset=utf-8",
+    },
+}) {
+    if (!(maybeUnresolved instanceof HtmlString)) {
+        maybeUnresolved = html `${maybeUnresolved + ""}`;
+    }
+    if (maybeUnresolved instanceof DangerJsonInHtml) {
+        maybeUnresolved = html `<div style="color:red;">
+      Use json and not dangerjson. The purpose of dangerjson is to be explicit
+      when you embed unescaped json elements in an html document.
+    </div>`;
+    }
+    const definitelyResolved = await maybeUnresolved.resolve(mini);
+    const flattend = definitelyResolved.flat(Infinity);
+    if (!(maybeUnresolved instanceof JsonString)) {
+        flattend.unshift(/*html*/ `<!DOCTYPE html>
+      <html>
+        <head>
+          ${Reloader} ${head}
+        </head>
+        <body>
+      `);
+    }
+    else {
+        const headers = {
+            ...options.headers,
+            ...{ "Content-Type": "application/json; charset=utf-8" },
+        };
+        options.headers = headers;
+    }
+    async function* stepGen() {
+        let index = 0;
+        while (index < flattend.length) {
+            yield flattend[index++];
+        }
+    }
+    function Stream(a) {
+        return a;
+    }
+    return new Response(Stream(stepGen), options);
+}
+/**
+ * Generic html error type guard
+ * @param submissionResult output of some function
+ * @returns boolean - true if the given object has a property called "error" and its value is an instance of HtmlString
+ */
+export function isError(submissionResult) {
+    return ("error" in submissionResult && submissionResult.error instanceof HtmlString);
+}

package/dist/mininext.d.ts

@@ -0,0 +1,4 @@
+import { url, Mini, type HtmlHandler } from "./url";
+import { html, isError, HtmlString, head } from "./html";
+declare function build(backendPath?: string): Promise<void>;
+export { url, html, head, build, isError, HtmlString, type HtmlHandler, Mini };

package/dist/mininext.js

@@ -0,0 +1,115 @@
+import { url, Mini } from "./url";
+import { html, isError, HtmlString, head } from "./html";
+import { watch } from "fs/promises";
+import * as path from "path";
+const PROJECT_ROOT = import.meta.dir + "/../";
+async function build(backendPath = "backend/backend.ts") {
+    await buildBackend(backendPath);
+    if (Bun.argv[2] === "dev") {
+        await devServer();
+    }
+}
+const myPlugin = {
+    name: "node buffer in the frontend",
+    setup(build) {
+        build.onResolve({ filter: /^buffer$/ }, (args) => {
+            const path_to_buffer_lib = path.resolve(PROJECT_ROOT, "node_modules/buffer/index.js");
+            if (path_to_buffer_lib)
+                return {
+                    path: path_to_buffer_lib,
+                };
+        });
+    },
+};
+async function buildBackend(backendPath = "backend/backend.ts") {
+    global.FrontendScriptUrls = [];
+    global.FrontendScripts = [];
+    global.bundledSVGs = {};
+    const i = await import(path.resolve(PROJECT_ROOT, backendPath));
+    for (const frontend of url.getFrontends()) {
+        const f = await buildFrontend(frontend);
+        FrontendScriptUrls.push("/" + f.url);
+        FrontendScripts.push(f.script);
+    }
+    for (const svgPath of url.getSvgPaths()) {
+        const parsedSvgPath = path.parse(svgPath);
+        const svgContent = Bun.file(path.join(PROJECT_ROOT + "/backend/", svgPath));
+        const svgHash = Bun.hash(await svgContent.arrayBuffer());
+        const svgUrl = `/${parsedSvgPath.name}-${svgHash}.svg`;
+        bundledSVGs[svgUrl] = {
+            svgContent: await svgContent.text(),
+            svgPath,
+        };
+    }
+    const res = await Bun.build({
+        entrypoints: [path.resolve(PROJECT_ROOT, backendPath)],
+        outdir: path.resolve(PROJECT_ROOT, "dist"),
+        naming: "backend.js",
+        minify: Bun.argv[2] === "dev" ? false : true, //production
+        target: "node",
+        define: {
+            FrontendScripts: JSON.stringify(FrontendScripts),
+            FrontendScriptUrls: JSON.stringify(FrontendScriptUrls),
+            bundledSVGs: JSON.stringify(bundledSVGs),
+        },
+    });
+}
+async function buildFrontend(file) {
+    const result = await Bun.build({
+        entrypoints: [path.resolve(PROJECT_ROOT, `frontend/${file}`)],
+        outdir: path.resolve(PROJECT_ROOT, "dist"),
+        naming: "[name]-[hash].[ext]",
+        minify: Bun.argv[2] === "dev" ? false : true, //production
+        target: "browser",
+        plugins: [myPlugin],
+    });
+    if (!result?.outputs[0]?.path)
+        console.log(result);
+    const url = path.basename(result.outputs[0].path);
+    //results.push({ file, p });
+    return { url, script: await result.outputs[0].text() };
+}
+async function devServer() {
+    //start the reloader and tell browser to refresh once
+    await buildBackend();
+    let refreshed_once = false;
+    const server = Bun.serve({
+        port: 3001,
+        fetch(request) {
+            const success = server.upgrade(request);
+            return success
+                ? new Response("Reloader works!")
+                : new Response("Reloader WebSocket upgrade error", { status: 400 });
+        },
+        websocket: {
+            open(ws) {
+                ws.subscribe("reloader");
+                if (!refreshed_once) {
+                    ws.send("Reload!");
+                    refreshed_once = true;
+                }
+            },
+            message(ws, message) { }, // a message is received
+        },
+    });
+    async function watchAndBuild(dir) {
+        try {
+            //start the file watcher that will rebuild frontend on save
+            const watcher = watch(path.resolve(PROJECT_ROOT, dir), {
+                recursive: true,
+            });
+            for await (const event of watcher) {
+                buildBackend().then(() => {
+                    // tell browser to refresh again because we saw a change
+                    server.publish("reloader", "Reload!");
+                });
+            }
+        }
+        catch (e) {
+            console.log(`mini-next dev server has trouble watching "./${dir}", does the directory exist?`);
+        }
+    }
+    watchAndBuild("frontend");
+    watchAndBuild("backend");
+}
+export { url, html, head, build, isError, HtmlString, Mini };

package/dist/url.d.ts

@@ -0,0 +1,191 @@
+import { html, json, dangerjson, HtmlString } from "./html";
+import type { DangerJsonInHtml, JsonString, JsonStringValues } from "./html";
+export type Form = {
+    post: boolean;
+    urlencoded: boolean;
+    multipart: boolean;
+    formJson?: any;
+    formData?: FormData;
+    formName?: string;
+    hiddenField?: HtmlString;
+    actionlink<Y = undefined>(qs?: string[] | string, settings?: LinkSettings): (mini: Mini<Y>) => string;
+    onPostSubmit<F>(cb: () => F): F | undefined;
+};
+export type DataMaker<X> = ((mini: Mini) => DataMakerReturnType<X>) | (() => DataMakerReturnType<X>);
+export type DataMakerReturnType<X> = X | Promise<X>;
+export type HandlerReturnType = JsonString | DangerJsonInHtml | HtmlString | string | void;
+export type LazyHandlerReturnType = HandlerReturnType | Promise<HandlerReturnType>;
+export type NamedForm<Z> = {
+    formResponse: LazyHandlerReturnType;
+    formInfo?: Z;
+};
+export type NamedFormHandlerReturnType<X> = HandlerReturnType | Promise<HandlerReturnType> | NamedForm<X> | Promise<NamedForm<X>>;
+/**
+ * Mini - the data object can be filled with url.data
+ * @example
+ * ``` js
+ * const {html,json, css, data, req, form, link, svg, deliver, route, params, header, head } = mini  //pull everything out of the mini handbag
+ * ```
+ */
+export declare class Mini<X = undefined> {
+    html: typeof html<X>;
+    css: typeof html<X>;
+    json: typeof json<X>;
+    dangerjson: typeof dangerjson<X>;
+    data: X;
+    req: Request;
+    head: (head: HtmlString) => undefined;
+    headers: (headers: HeadersInit, overwrite?: boolean) => undefined;
+    options: (options: ResponseInit) => undefined;
+    deliver: typeof url.deliver;
+    route: string;
+    params: URLSearchParams;
+    form: Form;
+    constructor(mini: Mini<undefined | any>, data: X);
+}
+/**
+ * HtmlHandler
+ * @param mini - the mini object
+ * @returns - return a partially resolved html string with mini.html
+ * @example
+ * ``` js
+ * const {html,json, css, data, req, form, link, svg, deliver, route, params, header, head } = mini  //pull everything out of the mini handbag
+ * ```
+ */
+export type HtmlHandler<Y = undefined> = ((mini: Mini<Y>) => LazyHandlerReturnType) | (() => LazyHandlerReturnType);
+export type NamedFormHandler<Y = undefined, Z = undefined> = ((mini: Mini<Y>) => NamedFormHandlerReturnType<Z>) | (() => NamedFormHandlerReturnType<Z>);
+declare global {
+    var FrontendScripts: Array<string>;
+    var FrontendScriptUrls: Array<string>;
+    var bundledSVGs: Record<string, {
+        svgContent: string;
+        svgPath: string;
+    }>;
+}
+export type ScriptTag = (...params: any[]) => Promise<HtmlString>;
+interface LinkSettings {
+    [key: string]: string | null | undefined;
+}
+export declare class url {
+    static direct_handlers_html: ReadonlyMap<string, HtmlHandler>;
+    private static frontends;
+    private static svgs;
+    static svg(path: string, options?: ResponseInit): string | undefined;
+    static frontend(path: string, snippet?: HtmlString): HtmlString;
+    /**
+     * This is used by the frontend bundler in order to find all frontends and their corresponding script files.
+     */
+    static getFrontends(): string[];
+    static getSvgPaths(): string[];
+    static serveFrontend(req: Request): Response | undefined;
+    static serveSvg(req: Request): Response | undefined;
+    /**
+     * tool to expose data to a frontend as a global variable.
+     * @param name  this will be added as window.name to the window object in the frontend
+     * @param value this will be parsed as json in the frontend and asigned as follows: window.name = JSON.parsed(value)
+     * @returns the script tag to be embeded in the html response
+     *
+     * @example
+     * ``` js
+     * //backend
+     * url.deliver("user", userData); // window.user = JSON.parse(userData)
+     * //frontend
+     * const user = window["user"];
+     * ```
+     * if you want to use types, declare them like so in your frontend code:
+     * ``` ts
+     * declare global {
+     * var user: string;
+     *}
+     * ```
+     */
+    static deliver(name: string, value: JsonStringValues): HtmlString;
+    /**
+     * @param dataHandler the function that prepares the data for the handlers
+     * @example const {html,json, css, data, req, form, link, svg, deliver, route, params, header, head } = mini  //pull everything out of the mini handbag
+     * @returns
+     */
+    static data<T>(dataMaker: DataMaker<T>): {
+        /**
+         * @param dataHandler the function that prepares the data for the handlers
+         * @example const {html,json, css, data, req, form, link, svg, deliver, route, params, header, head } = mini  //pull everything out of the mini handbag
+         * @returns
+         */
+        handler: (dataHandler: HtmlHandler<T>) => (oldmini: Mini) => Promise<string | void | DangerJsonInHtml>;
+        /**
+         * use this to **specify the input type for the functions**,
+         *
+         * that you want to use in the HtmlHandlers that follow this **data blend!**
+         * @example type lol = typeof MaybeLoggedIn.$Mini
+         */
+        $Mini: Mini<T>;
+        /**
+         * use this to **specify the input type for the functions**,
+         *
+         * that you want to use in the Htmlhandlers that follow this **data blend!**
+         * @example type haha = Mini<typeof MaybeLoggedIn.$Data>
+         */
+        $Data: T;
+    };
+    /**
+     * use this to define your routes.
+     * @example
+     * ``` js
+     *    url.set([
+     *      ["/", (mini) => mini.html`<h1>Hello world</h1>`],
+     *      ["/apple", (mini) => mini.html`<h1>Hello apple</h1>`],
+     *      ["/banana", (mini) => mini.html`<h1>Hello banana</h1>`],
+     *    ]);
+     * ```
+     */
+    static set<K extends string>(entries: [K, HtmlHandler][]): void;
+    /**
+     * wrap your handlers in this if you mutate something to prevent CSRF issues.
+     * @param handler - normal html handler with mini as the argument
+     * @returns a wrapped html handler that will only be called when the request is post
+     */
+    static post(handler: HtmlHandler): (mini: Mini) => LazyHandlerReturnType;
+    /**
+     * wrap your handlers in this if you mutate something to prevent CSRF issues.
+     * @param handler - normal html handler with mini as the argument
+     * @returns a wrapped html handler that will only be called when the request is post and contains a json body
+     */
+    static postJson(handler: HtmlHandler): (mini: Mini) => LazyHandlerReturnType;
+    /**
+     * wrap your handlers in this if you mutate something to prevent CSRF issues.
+     * @param handler - normal html handler with mini as the argument
+     * @returns a wrapped html handler that will only be called when the request is post and contains a FormData body
+     */
+    static postFormData(handler: HtmlHandler): (mini: Mini) => LazyHandlerReturnType;
+    /**
+     * This is useful to decouple forms from routes.
+     * @param name name of the form - mini.form.onPostSubmit() will only be called if a (possibly hidden) field called formName matches this
+     * @param handler just like a normal handler (aka you can return the form as a HtmlString), but you can optionally return additional data in formInfo
+     * @returns - { formResponse: result of the handler, formInfo?: some info about the form. Totally up to you}
+     */
+    static namedForm<X = undefined, Z = undefined>(name: string, handler: NamedFormHandler<X, Z>): (mini: Mini<X>) => Promise<NamedForm<Z>>;
+    /**
+     * pass in all the query string parameter names that you want to preserve in the link
+     * @param Url - the url that you want to link to (example: "/login")
+     * @param qs - the query string parameters that you want to preserve in the link
+     * @param settings - key and string values that you want to set in the link
+     * @returns - the link that you can use in your html template
+     */
+    static link<X>(Url: string, qs?: string[] | string, settings?: LinkSettings): (mini: Mini<X>) => string;
+    static currylink(Url: string, qs: string[] | string, req: Request, settings?: LinkSettings): string;
+    /**
+     * This method retrieves a url from the urls array. If the url does not exist in the urls array, an error will be thrown.
+     * @param {string} Url - The url to retrieve.
+     * @return {string} - The retrieved url.
+     * @throws Will throw an Error if the provided url is not found in the urls array.
+     */
+    static get(Url: string): string;
+    static match(req: Request, reqPath?: string): Promise<Response | undefined>;
+    /**
+     * Fetch handler that is called by the server when a request is made to any of the urls.
+     * @param {Request} req - The Request object.
+     * @return {Promise<Response>} - The Response object.
+     */
+    static install(req: Request): Promise<Response>;
+}
+export {};