@spirobel/mininext 0.7.6 → 0.8.0

package/dist/html.js

@@ -1,288 +0,0 @@
-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.
-     * it can also become unresolved if an unresolved HtmlString is passed into it as a value
-     */
-    resolved = true;
-    async resolve(mini) {
-        if (this.resolved)
-            return this;
-        for (const [index, htmlPiece] of this.entries()) {
-            if (htmlPiece instanceof HtmlString) {
-                let resolvedHtmlPiece = await htmlPiece.resolve(mini);
-                if (this instanceof JsonString || this instanceof DangerJsonInHtml) {
-                    this[index] = JSON.stringify(resolvedHtmlPiece);
-                }
-                else {
-                    this[index] = resolvedHtmlPiece;
-                }
-            }
-            else if (typeof htmlPiece === "function") {
-                let resolvedHtmlPiece = await htmlPiece(mini); //passing mini
-                //same cases as outer if statement
-                if (resolvedHtmlPiece instanceof HtmlString) {
-                    resolvedHtmlPiece = await resolvedHtmlPiece.resolve(mini);
-                }
-                else if (htmlPiece instanceof BasedHtml) {
-                    this[index] = htmlPiece;
-                }
-                else {
-                    if (this instanceof JsonString || this instanceof DangerJsonInHtml) {
-                        resolvedHtmlPiece = JSON.stringify(resolvedHtmlPiece);
-                    }
-                    else {
-                        const notEmpty = resolvedHtmlPiece || "";
-                        // values will be escaped by default
-                        resolvedHtmlPiece = Bun.escapeHTML(notEmpty + "");
-                    }
-                }
-                // Replace the function with the resolved HTML piece in place
-                this[index] = resolvedHtmlPiece;
-            }
-            else if (htmlPiece instanceof BasedHtml) {
-                this[index] = htmlPiece;
-            }
-        }
-        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 in the HtmlResponder
-            if (Array.isArray(value) &&
-                value.every((val) => val instanceof HtmlString || val instanceof BasedHtml)) {
-                // If the value is an array of HtmlString objects, add the whole array as a single value
-                const notResolved = new HtmlString(...value);
-                notResolved.resolved = false;
-                values[index] = notResolved;
-                htmlStringArray.resolved = false; // we could bother with .find here
-            }
-            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 || value instanceof BasedHtml)) {
-                const notEmpty = value || "";
-                // values will be escaped by default
-                values[index] = Bun.escapeHTML(notEmpty + "");
-            }
-            else if (value instanceof HtmlString) {
-                if (!value.resolved) {
-                    htmlStringArray.resolved = false;
-                }
-            }
-            htmlStringArray.push(values[index]);
-        }
-    }
-    return htmlStringArray;
-}
-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 in the HtmlResponder
-                if (Array.isArray(value) &&
-                    value.every((val) => val instanceof HtmlString || val instanceof BasedHtml)) {
-                    // If the value is an array of HtmlString objects, add the whole array as a single value
-                    const notResolved = new HtmlString(...value);
-                    notResolved.resolved = false;
-                    values[index] = notResolved;
-                    jsonStringArray.resolved = false; // we could bother with .find here
-                }
-                else if (typeof value === "function") {
-                    jsonStringArray.resolved = false;
-                    values[index] = value;
-                }
-                else if (value instanceof HtmlString || value instanceof BasedHtml) {
-                    if (value instanceof HtmlString && !value.resolved) {
-                        jsonStringArray.resolved = false;
-                    }
-                    values[index] = value;
-                }
-                else if (!(value instanceof JsonString)) {
-                    // values will be turned into a JSON string
-                    if (value) {
-                        values[index] = JSON.stringify(value);
-                    }
-                }
-                jsonStringArray.push(values[index]);
-            }
-        }
-        return jsonStringArray;
-    };
-}
-export const json = JsonTemplateProcessor();
-export const dangerjson = JsonTemplateProcessor(true);
-export const commonHead = html ` <meta
-    name="viewport"
-    content="width=device-width, initial-scale=1.0"
-  />
-  <script>
-    /* prevent form resubmission */
-    if (window.history.replaceState) {
-      window.history.replaceState(null, null, window.location.href);
-    }
-  </script>`;
-export const cssReset = html ` <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>`;
-let default_head = (mini) => mini.html `
-  <title>mini-next</title>
-  ${commonHead} ${cssReset}
-`;
-/**
- * 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((mini)=>mini.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>`;
-    }
-    if (!(maybeUnresolved instanceof JsonString)) {
-        const reloader = new HtmlString();
-        reloader.push(global.Reloader || "");
-        maybeUnresolved = html `<!DOCTYPE html>
-      <html>
-        <head>
-          ${reloader} ${head}
-        </head>
-        <body>
-          ${maybeUnresolved}
-        </body>
-      </html> `;
-    }
-    else {
-        const headers = {
-            ...options.headers,
-            ...{ "Content-Type": "application/json; charset=utf-8" },
-        };
-        options.headers = headers;
-    }
-    const definitelyResolved = await maybeUnresolved.resolve(mini);
-    const flattend = definitelyResolved.flat(Infinity);
-    async function* stepGen() {
-        let index = 0;
-        while (index < flattend.length) {
-            const step = flattend[index++];
-            if (step)
-                yield String(step);
-        }
-    }
-    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);
-}
-/**
- * The difference between this and HtmlString is that it is fully resolved and only accepts primitive types.
- * In plain english this means:
- * It does not accept functions (that will be resolved at request time with (mini)=>mini.html) like mini.html does.
- */
-export class BasedHtml extends String {
-}
-//TODO make it so we can embed BasedHtml into mini.html partially resolved html strings
-/**
- * The difference between this and HtmlString is that it is fully resolved and only accepts primitive types.
- * @param strings - html literals
- * @param values - values will get escaped to prevent xss
- * @returns
- */
-export const basedHtml = (strings, ...values) => {
-    // Apply escapeHtml to each value before using them in the template string
-    // In case it didn't already get escaped
-    for (const [index, value] of values.entries()) {
-        // we can pass arrays of BasedHtml and they will get flattened automatically
-        if (Array.isArray(value) &&
-            value.every((val) => val instanceof BasedHtml)) {
-            // If the value is an array of BasedHtml objects, flatten it and add to ...values
-            values[index] = value.join("");
-        }
-        else if (!(value instanceof BasedHtml)) {
-            const notEmpty = value || "";
-            // values will be escaped by default
-            values[index] = Bun.escapeHTML(notEmpty + "");
-        }
-    }
-    return new BasedHtml(String.raw({ raw: strings }, ...values));
-};

package/dist/url.d.ts

@@ -1,282 +0,0 @@
-/// <reference types="bun-types" />
-/// <reference types="bun-types" />
-/// <reference types="bun-types" />
-/// <reference types="bun-types" />
-/// <reference types="bun-types" />
-/// <reference types="bun-types" />
-/// <reference types="bun-types" />
-/// <reference types="bun-types" />
-import type { Server, WebSocketHandler, RouterTypes, BunRequest } from "bun";
-import { html, json, dangerjson, HtmlString } from "./html";
-import { BasedHtml, type DangerJsonInHtml, type JsonString, type JsonStringValues } from "./html";
-export type HTTPMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
-export type MiniNextRouteHandlerObject<T extends string> = {
-    [K in HTTPMethod]?: HtmlHandler<unknown, T>;
-};
-export type MiniNextRouteValue<T extends string> = HtmlHandler<unknown, T> | MiniNextRouteHandlerObject<T>;
-export type BunRoutes<R extends {
-    [K in keyof R]: RouterTypes.RouteValue<Extract<K, string>>;
-}> = R;
-export type MiniNextRoutes = Record<string, MiniNextRouteValue<"">>;
-/**
- * A helper function that helps narrow unknown objects
- * @param object - the object of type unknown that is to be narrowed
- * @param key - the key that may or may not exist in object
- * @returns true if the key is present and false if not
- * @example
- * ``` js
- * has(this.form.formJson, "formName") &&
- * this.form.formJson.formName === this.form.formName
- * ```
- * https://stackoverflow.com/questions/70028907/narrowing-an-object-of-type-unknown
- */
-export declare function has<T, K extends string>(object: T, key: K): object is T & object & Record<K, unknown>;
-export type Form = {
-    post: boolean;
-    urlencoded: boolean;
-    multipart: boolean;
-    formJson?: unknown;
-    formData?: FormData;
-    formName?: string;
-    hiddenField?: HtmlString;
-    actionlink<Y = unknown>(qs?: string[] | string, settings?: LinkSettings): (mini: Mini<Y>) => string;
-    onPostSubmit<F>(cb: () => F): F | undefined;
-};
-export type DataMaker<X, Z = unknown> = ((mini: Mini, rerun?: Z) => 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 = unknown, ROUTE extends string = ""> {
-    html: typeof html<X>;
-    css: typeof html<X>;
-    json: typeof json<X>;
-    dangerjson: typeof dangerjson<X>;
-    data: X;
-    req: BunRequest<ROUTE>;
-    head: (head: HtmlHandler | HtmlString) => undefined;
-    headers: (headers: HeadersInit, overwrite?: boolean) => undefined;
-    options: (options: ResponseInit) => undefined;
-    deliver: typeof url.deliver;
-    route: string;
-    params: URLSearchParams;
-    form: Form;
-    requrl: Readonly<URL>;
-    /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/redirect_static) */
-    redirect: (url: string | URL, status?: number) => void;
-    constructor(mini: Mini<unknown>, 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 = unknown, ROUTE extends string = ""> = ((mini: Mini<Y, ROUTE>) => LazyHandlerReturnType) | (() => LazyHandlerReturnType);
-export type NamedFormHandler<Y = unknown, Z = undefined> = ((mini: Mini<Y>) => NamedFormHandlerReturnType<Z>) | (() => NamedFormHandlerReturnType<Z>);
-declare global {
-    var bundledFrontends: Record<string, {
-        frontendFilePath: string;
-        frontendContent: string;
-        position: number;
-    }>;
-    var bundledSVGs: Record<string, {
-        svgContent: string;
-        svgFilePath: string;
-        options: ResponseInit;
-        position: number;
-    }>;
-}
-export type ScriptTag = (...params: any[]) => Promise<HtmlString>;
-interface LinkSettings {
-    [key: string]: string | null | undefined;
-}
-export declare class url {
-    static websocket: WebSocketHandler | undefined;
-    static server: Server;
-    static routes: MiniNextRoutes;
-    static direct_handlers_html: Map<string, HtmlHandler>;
-    private static frontends;
-    private static svgs;
-    /**
-     * This function takes care of bundling your svg (icons?) into the webapp
-     * they will have a hash in the name to break the cache when needed
-     * @param svgFilePath first place to look: svgs folder in the same path the calling file, after that path from project root.
-     * @param options ResponseInit, default headers for an svg
-     * @returns url to the svg
-     */
-    static svg(svgFilePath: string, options?: ResponseInit): string | undefined;
-    /**
-     * this function helps you build frontends with any kind of framework (no framework at all) and get the bundle
-     * @param path first place to look: frontend folder in the same path the calling file, after that /frontend path from project root.
-     * @param snippet this is handy to pass in a piece of html that often goes along with a certain frontend
-     * @returns a html script element with the bundled frontend as the src
-     */
-    static frontend<X>(frontendFilePath: string, snippet?: BasedHtml): HtmlString;
-    static frontend<X>(frontendFilePath: string, snippet?: HtmlHandler<X>): (mini: Mini<X>) => HtmlString;
-    /**
-     * This is used by the frontend bundler in order to find all frontends and their corresponding script files.
-     */
-    static getFrontends(): {
-        frontendFilePath: string;
-        callerPath: string;
-        position: number;
-    }[];
-    static getSvgs(): {
-        svgFilePath: string;
-        callerPath: string;
-        position: number;
-        options: ResponseInit;
-    }[];
-    /**
-     * 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, Z>(dataMaker: DataMaker<T, Z>): {
-        /**
-         * @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 | JsonString>;
-        dataMaker: DataMaker<T, Z>;
-        /**
-         * 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
-     *   //define all routes at once
-     *    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>`],
-     *    ]);
-     *    //define or overwrite just one route
-     *  url.set("/apple", (mini)=>mini.html`<h1> Hello pineapple </h1>`)
-     * ```
-     */
-    static set<K extends string>(entries: [K, HtmlHandler][]): void;
-    static set<R extends {
-        [X in keyof R]: MiniNextRouteValue<Extract<X, string>>;
-    }>({ routes }: {
-        routes: R;
-    }): void;
-    static set(urlPath: string, handler: 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 = unknown, 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;
-    /**
-     * users expect links to work with or without a trailing slash.
-     * Developers expect that that links work with or without a preceding slash.
-     * We make sure that these expectations are met when using url.set and url.get.
-     * (by adding all the variations to the url.direct_handlers Map)
-     * @param {string} inputString - the url
-     * @returns {string[]} - returns array of variations (added slash in the beginning, added, removed slash at the end)
-     */
-    static generateVariations(inputString: string): string[];
-    static handleWithMini(req: BunRequest<string>, server: Server, handler: HtmlHandler): Promise<Response>;
-    /**
-     * use this to set the Websocket object. Check out [the bun docs](https://bun.sh/docs/api/websockets) for more details.
-     * @param wsObject the websocketsocket object {@link WebSocketHandler}
-     */
-    static setWebsocket<T = undefined>(wsObject: WebSocketHandler<T>): void;
-    /**
-     * Send a message to all connected {@link ServerWebSocket} subscribed to a topic
-     * @param topic The topic to publish to
-     * @param message The data to send
-     * @returns 0 if the message was dropped, -1 if backpressure was applied, or the number of bytes sent.
-     */
-    static publishHtml(topic: string, message: BasedHtml): number;
-    /**
-     * 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(): {
-        fetch: (req: Request, server: Server) => Response;
-        websocket: WebSocketHandler<undefined> | undefined;
-        routes: Record<string, RouterTypes.RouteValue<string>>;
-    };
-}
-export {};