elegance-js 2.1.23 → 2.1.26

package/dist/client/state.js

@@ -0,0 +1,110 @@
+import { compilerStore } from "../compilation/compiler.js";
+import { raw } from "../elements/raw.js";
+import { loadHook } from "./loadHook.js";
+class ServerSubject {
+    constructor(id, value) {
+        this.id = id;
+        this.value = value;
+    }
+    /**
+     * Create a client-side reactiveMap, that dynamically updates itself whenever the subject changes.
+     *
+     * **IMPORTANT** `callback` is sent literally to the browser, and thus doesn't have access to server-side variables, and is untrusted.
+     * @param callback Client side templating function that gets each entry of T, and returns an EleganceElement.
+     * @returns An HTML represent used to track the position of the reactive map.
+     */
+    reactiveMap(callback) {
+        if (!callback) {
+            throw new Error("No template provided for reactiveMap.");
+        }
+        if (Array.isArray(this.value) === false) {
+            throw new Error("Reactive maps can only be used on arrays.");
+        }
+        const store = compilerStore.getStore();
+        if (!store) {
+            throw new Error("reactiveMap() can only be invoked during the build process of a page or layout.");
+        }
+        const mapId = state(store.generateId());
+        const templateState = state(callback);
+        loadHook((templateState, thisState, mapId) => {
+            let trackedElements = [];
+            function updateCallback() {
+                const mapTemplateElement = document.querySelector(`template[map-id="${mapId.value}"]`);
+                if (!mapTemplateElement) {
+                    DEV_BUILD: throw new Error("The DOM has been mutated and no longer contains the required template element to create an track the reactiveMap of subject with id: " + thisState.id);
+                    return;
+                }
+                for (const elem of trackedElements) {
+                    elem.parentElement?.removeChild(elem);
+                }
+                trackedElements = [];
+                for (const value of thisState.value) {
+                    const result = templateState.value(value);
+                    const instanceHTML = eleganceClient.createHTMLElementFromElement(result);
+                    mapTemplateElement.parentElement?.insertBefore(instanceHTML.root, mapTemplateElement);
+                    trackedElements.push(instanceHTML.root);
+                }
+            }
+            const callbackId = Date.now().toString();
+            thisState.observe(callbackId, updateCallback);
+            updateCallback();
+            return () => {
+                thisState.unobserve(callbackId);
+            };
+        }, [templateState, this, mapId]);
+        return template({ "map-id": mapId.value, });
+    }
+    /**
+     * Allows the use of a ServerSubject as the child of an EleganceElement.
+     *
+     * Returns an HTML string that will be removed on page-load in the client and replaced with the appropriate value.
+     * @returns HTML string
+     */
+    generateObserverNode() {
+        return raw(`<template o="${this.id}"></template>`);
+    }
+    toString() {
+        return this.generateObserverNode();
+    }
+    serialize() {
+        let result = `{id:"${this.id}",value:`;
+        switch (typeof this.value) {
+            case "string":
+                result += `"${this.value}"`;
+                break;
+            case "function":
+                result += `${this.value.toString()}`;
+                break;
+            case "object":
+                if (Array.isArray(this.value)) {
+                    result += `${JSON.stringify(this.value)}`;
+                    break;
+                }
+            default:
+                result += JSON.stringify(this.value);
+                break;
+        }
+        result += "}";
+        return result;
+    }
+}
+/**
+ * Create a reactive ServerSubject which will be serialized and sent to the browser.
+ *
+ * Once in the callback of a loadHook, eventListener, etc. it will become a *ClientSubject*.
+ * @param value Any value you want to be accessible in the browser. Value is sent literally as-is. Functions are supported.
+ * @param options Set options for the state (usually unused)
+ * @returns An instance of ServerSubject you can use as a reference to this state in functions like `loadHook()`
+ */
+function state(value, options) {
+    const store = compilerStore.getStore();
+    if (!store) {
+        const message = "Illegal invocation of state(). Ensure that the state() function is only called inside components, and never at the top-level of a page or layout.";
+        throw new Error(message);
+    }
+    const subjectId = options?.explicitId ?? store.generateId();
+    const serverSubject = new ServerSubject(subjectId, value);
+    store.addClientToken(serverSubject);
+    return serverSubject;
+}
+export { state, ServerSubject, };

package/dist/compilation/compiler.d.ts

@@ -0,0 +1,155 @@
+/**
+ * This file contains the functions used by compiler_process to compile pages.
+ */
+import { AnyElement, SpecialElementOption } from "../elements/element";
+import { PageInformation } from "../server/page";
+import { LayoutInformation, LayoutProps } from "../server/layout";
+import { AsyncLocalStorage } from "async_hooks";
+import { IncomingMessage, ServerResponse } from "http";
+/** Context of a page that is currently being compiled. */
+type PageCompilationContext = {
+    /** The slash starting relative pathname (relative to pagesDirectory) of this page. */
+    pathname: string;
+    /**
+     * An id counter starting from 0, that is incremented once per generateID() call,
+     * and is used in conjunction with the pathname to generate unique static IDs (order-dependent)
+     */
+    idCounter: number;
+    usedHashes: string[];
+    /**
+     * Used by some tools to determine whether or not the current context is a page or a layout,
+     * useful for stuff like loadHooks, which behave differently in layouts and pages.
+     */
+    kind: "page" | "layout";
+};
+/** Context of a layout that is currently being compiled. */
+type LayoutCompilationContext = {
+    /** The slash starting relative pathname (relative to pagesDirectory) of this layout. */
+    pathname: string;
+    /**
+     * An id counter starting from 0, that is incremented once per generateID() call,
+     * and is used in conjunction with the pathname to generate unique static IDs (order-dependent)
+     */
+    idCounter: number;
+    usedHashes: string[];
+    /**
+     * Used by some tools to determine whether or not the current context is a page or a layout,
+     * useful for stuff like loadHooks, which behave differently in layouts and pages.
+     */
+    kind: "layout" | "page";
+};
+type CompilerOptions = {
+    pagesDirectory: string;
+    environment: "production" | "development";
+    publicDirectory: string;
+    outputDirectory: string;
+    doHotReload: boolean;
+};
+type CompiledLayout = {
+    /** Compiled result of the layoutConstructor */
+    layoutHTMLStart: string;
+    layoutHTMLEnd: string;
+    /** Client data tokens generated by the layoutConstructor & layoutMetadataConstructor during it's compilation. */
+    specialElementOptions: {
+        elementKey: string;
+        optionName: string;
+        optionValue: SpecialElementOption;
+    }[];
+    clientTokens: unknown[];
+    /** Compiled result of the layoutMetadataConstructor */
+    layoutMetadataHTML: string;
+    layoutProps: LayoutProps;
+};
+type CompiledPage = {
+    pageHTML: string;
+};
+/** The result of turning an element into a string and extracting any special options from it. */
+type SerializationResult = {
+    serializedElement: string;
+    specialElementOptions: {
+        elementKey: string;
+        optionName: string;
+        optionValue: SpecialElementOption;
+    }[];
+};
+declare let compilerOptions: CompilerOptions;
+/**
+ * We use asynclocalstorage instead of globals to get rid of race conditions.
+ * We run the code inside asynclocalstorage, and then all of the values get dumped into here instead of globalThis.
+ * A much cleaner approach than previous.
+ */
+type CompilerStore = {
+    generateId: () => string;
+    addClientToken: (value: unknown) => void;
+    compilationContext: PageCompilationContext | LayoutCompilationContext;
+    req?: IncomingMessage;
+    res?: ServerResponse;
+};
+declare const compilerStore: AsyncLocalStorage<CompilerStore>;
+declare function setCompilerOptions(newOptions: CompilerOptions): void;
+declare function generatePageCompilationContext(pathname: string): PageCompilationContext;
+declare function generateLayoutCompilationContext(pathname: string): LayoutCompilationContext;
+/**
+ * Ship any `node_modules` package to the browser.
+ * @param packages The packages to register for shipping to the browser.
+ */
+declare function clientPackages(packages: {
+    [globalName: string]: string;
+}): void;
+/**
+ * Take any element, and turn it into a valid HTML string.
+ * Throw an error whenever an element is considered invalid.
+ * @param compilationContext The context of the page or layout that we're compiling
+ * @param element The element to serialize.
+ * @returns The serialized element, and any special options that were encountered.
+ */
+declare function serializeElement(compilationContext: PageCompilationContext, element: AnyElement, path?: string[]): SerializationResult;
+/**
+ * This function uses string interpolation to transform client tokens and special element options into a script tag that is then sent to the client.
+ * The client tokens are not *fully* serialized, but the necessary components to re-create them as client versions of the corresponding thing *are* serialized.
+ * For example, the serialize() method of EventListener is not sent, but it's callback, id, and dependencies (as ids) are.
+ * String interpolation is dangerous and error-prone, so if you're going to add something to this function, ensure you know what you're doing,
+ * and make sure to also edit runtime.ts to handle the clientTokens that you send to the browser. I did not create separate datatypes in the runtime for the intermediary forms of things like EventListeners,
+ * LoadHooks, etc, for I did not feel it necessary, but do note that these types do not exactly line up 100%.
+ * @param compilationContext The current context of what we're compiling, can be either layout or page compilation context.
+ * @param specialElementOptions An array of special element options that were found during serialization of the elements of whatever we're currently compiling
+ * @param clientTokens An array of tokens that will be serialized and shipped within the pageDataScript.
+ * @returns A string containing the page data <script> tag.
+ */
+declare function generatePageDataScript(compilationContext: PageCompilationContext, specialElementOptions: {
+    elementKey: string;
+    optionName: string;
+    optionValue: SpecialElementOption;
+}[], clientTokens: unknown[]): Promise<string>;
+declare function compilePageToDisk(allLayouts: Map<string, LayoutInformation>, pageInformation: PageInformation): Promise<CompiledPage>;
+declare function compilePage(allLayouts: Map<string, LayoutInformation>, pageInformation: PageInformation, reqRes?: {
+    req?: IncomingMessage | undefined;
+    res?: ServerResponse | undefined;
+}, extraParams?: Record<string, unknown>): Promise<CompiledPage>;
+declare function compileLayoutToDisk(layoutInformation: LayoutInformation, allLayouts: Map<string, LayoutInformation>): Promise<void>;
+declare function compileLayout(layoutInformation: LayoutInformation, allLayouts: Map<string, LayoutInformation>, reqRes?: {
+    req?: IncomingMessage;
+    res?: ServerResponse;
+}): Promise<CompiledLayout>;
+/**
+ * Run the general compilation process for the project.
+ * This compiles all static-pages & static-layouts, as well as gathers a list of every page (dynamic and static) & layout (dynamic and static).
+ * It also recursively copies your public directory into the distribution directory.
+ * If doHotReload is true, it will also enable hot-reloading.
+ */
+declare function compileEntireProject(): Promise<{
+    allPages: Map<string, PageInformation>;
+    allLayouts: Map<string, LayoutInformation>;
+    allStatusCodePages: Map<string, PageInformation>;
+    compiledStaticPages: Map<string, CompiledPage>;
+    compiledStaticLayouts: Map<string, CompiledLayout>;
+}>;
+/**
+ * Run the general compilation process for the project.
+ * This compiles all static-pages & static-layouts, as well as gathers a list of every page (dynamic and static) & layout (dynamic and static).
+ * It then writes those values to compilerOptions -> outputDirectory/DIST
+ * It also recursively copies your public directory into the distribution directory.
+ */
+declare function compileEntireProjectToDisk(): Promise<void>;
+export type { CompilerOptions, CompiledLayout, CompiledPage, };
+export { setCompilerOptions, generatePageCompilationContext, generateLayoutCompilationContext, serializeElement, generatePageDataScript, compileEntireProject, compileEntireProjectToDisk, compilePageToDisk, compileLayoutToDisk, compilerStore, compilerOptions, compilePage, compileLayout, clientPackages, };