edgexpress 3.0.0 → 3.0.2

package/src/edge/main.d.ts

@@ -0,0 +1,192 @@
+import { type Compiler } from '../compiler.js'
+import { type Processor } from '../processor.js'
+import { type EdgeRenderer } from './renderer.js'
+import type {
+  PluginFn,
+  TagContract,
+  EdgeGlobals,
+  EdgeOptions,
+  LoaderTemplate,
+  LoaderContract,
+} from '../types.js'
+/**
+ * Exposes the API to render templates, register custom tags and globals
+ */
+export declare class Edge {
+  #private
+  /**
+   * Create an instance of edge with given options
+   */
+  static create(options?: EdgeOptions): Edge
+  /**
+   * Reference to the registered processor handlers
+   */
+  processor: Processor
+  /**
+   * A flag to know if using compat mode
+   */
+  compat: boolean
+  /**
+   * The loader to load templates. A loader can read and return
+   * templates from anywhere. The default loader reads files
+   * from the disk
+   */
+  loader: LoaderContract
+  /**
+   * The underlying compiler in use
+   */
+  compiler: Compiler
+  /**
+   * The underlying compiler in use
+   */
+  asyncCompiler: Compiler
+  /**
+   * Globals are shared with all rendered templates
+   */
+  globals: EdgeGlobals
+  /**
+   * List of registered tags. Adding new tags will only impact
+   * this list
+   */
+  tags: {
+    [name: string]: TagContract
+  }
+  constructor(options?: EdgeOptions)
+  /**
+   * Re-configure an existing edge instance
+   */
+  configure(options: EdgeOptions): void
+  /**
+   * Register a plugin. Plugins are called only once just before
+   * a rendering a view.
+   *
+   * You can invoke a plugin multiple times by marking it as a
+   * recurring plugin
+   */
+  use<T extends any>(pluginFn: PluginFn<T>, options?: T): this
+  /**
+   * Mount named directory to use views. Later you can reference
+   * the views from a named disk as follows.
+   *
+   * ```
+   * edge.mount('admin', join(__dirname, 'admin'))
+   *
+   * edge.render('admin::filename')
+   * ```
+   */
+  mount(viewsDirectory: string | URL): this
+  mount(diskName: string, viewsDirectory: string | URL): this
+  /**
+   * Un Mount a disk from the loader.
+   *
+   * ```js
+   * edge.unmount('admin')
+   * ```
+   */
+  unmount(diskName: string): this
+  /**
+   * Add a new global to the edge globals. The globals are available
+   * to all the templates.
+   *
+   * ```js
+   * edge.global('username', 'virk')
+   * edge.global('time', () => new Date().getTime())
+   * ```
+   */
+  global(name: string, value: any): this
+  /**
+   * Add a new tag to the tags list.
+   *
+   * ```ts
+   * edge.registerTag('svg', {
+   *   block: false,
+   *   seekable: true,
+   *
+   *   compile (parser, buffer, token) {
+   *     const fileName = token.properties.jsArg.trim()
+   *     buffer.writeRaw(fs.readFileSync(__dirname, 'assets', `${fileName}.svg`), 'utf-8')
+   *   }
+   * })
+   * ```
+   */
+  registerTag(tag: TagContract): this
+  /**
+   * Register an in-memory template.
+   *
+   * ```ts
+   * edge.registerTemplate('button', {
+   *   template: `<button class="{{ this.type || 'primary' }}">
+   *     @!yield($slots.main())
+   *   </button>`,
+   * })
+   * ```
+   *
+   * Later you can use this template
+   *
+   * ```edge
+   * @component('button', type = 'primary')
+   *   Get started
+   * @endcomponent
+   * ```
+   */
+  registerTemplate(templatePath: string, contents: LoaderTemplate): this
+  /**
+   * Remove the template registered using the "registerTemplate" method
+   */
+  removeTemplate(templatePath: string): this
+  /**
+   * Get access to the underlying template renderer. Each render call
+   * to edge results in creating an isolated renderer instance.
+   */
+  onRender(callback: (renderer: EdgeRenderer) => void): this
+  /**
+   * Returns a new instance of edge. The instance
+   * can be used to define locals.
+   */
+  createRenderer(): EdgeRenderer
+  /**
+   * Render a template with optional state
+   *
+   * ```ts
+   * edge.render('welcome', { greeting: 'Hello world' })
+   * ```
+   */
+  render(templatePath: string, state?: Record<string, any>): Promise<string>
+  /**
+   * Render a template asynchronously with optional state
+   *
+   * ```ts
+   * edge.render('welcome', { greeting: 'Hello world' })
+   * ```
+   */
+  renderSync(templatePath: string, state?: Record<string, any>): string
+  /**
+   * Render a template with optional state
+   *
+   * ```ts
+   * edge.render('welcome', { greeting: 'Hello world' })
+   * ```
+   */
+  renderRaw(contents: string, state?: Record<string, any>, templatePath?: string): Promise<string>
+  /**
+   * Render a template asynchronously with optional state
+   *
+   * ```ts
+   * edge.render('welcome', { greeting: 'Hello world' })
+   * ```
+   */
+  renderRawSync(templatePath: string, state?: Record<string, any>): string
+  /**
+   * Share locals with the current view context.
+   *
+   * ```js
+   * const view = edge.createRenderer()
+   *
+   * // local state for the current render
+   * view.share({ foo: 'bar' })
+   *
+   * view.render('welcome')
+   * ```
+   */
+  share(data: Record<string, any>): EdgeRenderer
+}

package/src/edge/main.js

@@ -0,0 +1,334 @@
+"use strict";
+/*
+ * edge.js
+ *
+ * (c) EdgeJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Edge = void 0;
+const loader_js_1 = require("../loader.js");
+const Tags = __importStar(require("../tags/main.js"));
+const compiler_js_1 = require("../compiler.js");
+const template_js_1 = require("../template.js");
+const globals_js_1 = require("./globals.js");
+const processor_js_1 = require("../processor.js");
+const renderer_js_1 = require("./renderer.js");
+const supercharged_js_1 = require("../plugins/supercharged.js");
+/**
+ * Exposes the API to render templates, register custom tags and globals
+ */
+class Edge {
+    /**
+     * Create an instance of edge with given options
+     */
+    static create(options = {}) {
+        return new Edge(options);
+    }
+    /**
+     * An array of bundled plugins
+     */
+    #bundledPlugins = [];
+    /**
+     * An array of registered plugins
+     */
+    #plugins = [];
+    /**
+     * Array of registered renderer hooks
+     */
+    #renderCallbacks = [];
+    /**
+     * Reference to the registered processor handlers
+     */
+    processor = new processor_js_1.Processor();
+    /**
+     * A flag to know if using compat mode
+     */
+    compat = false;
+    /**
+     * Globals are shared with all rendered templates
+     */
+    globals = { ...globals_js_1.edgeGlobals };
+    /**
+     * List of registered tags. Adding new tags will only impact
+     * this list
+     */
+    tags = {};
+    constructor(options = {}) {
+        this.configure(options);
+        /**
+         * Registering bundled set of tags
+         */
+        Object.keys(Tags).forEach((name) => {
+            this.registerTag(Tags[name]);
+        });
+        this.#bundledPlugins.push({
+            fn: supercharged_js_1.pluginSuperCharged,
+            executed: false,
+            options: { recurring: !options.cache },
+        });
+    }
+    /**
+     * Re-configure an existing edge instance
+     */
+    configure(options) {
+        if (options.loader) {
+            this.loader = options.loader;
+        }
+        else if (!this.loader) {
+            this.loader = new loader_js_1.Loader();
+        }
+        this.compiler = new compiler_js_1.Compiler(this.loader, this.tags, this.processor, {
+            cache: !!options.cache,
+            async: false,
+        });
+        this.asyncCompiler = new compiler_js_1.Compiler(this.loader, this.tags, this.processor, {
+            cache: !!options.cache,
+            async: true,
+        });
+    }
+    /**
+     * Execute plugins
+     */
+    #executePlugins() {
+        /**
+         * Running user-land plugins
+         */
+        this.#plugins
+            .filter(({ options, executed }) => {
+            if (options && options.recurring) {
+                return true;
+            }
+            return !executed;
+        })
+            .forEach((plugin) => {
+            plugin.fn(this, !plugin.executed, plugin.options);
+            plugin.executed = true;
+        });
+        /**
+         * Running bundled plugins after the user-land
+         * plugins
+         */
+        this.#bundledPlugins
+            .filter(({ options, executed }) => {
+            if (options && options.recurring) {
+                return true;
+            }
+            return !executed;
+        })
+            .forEach((plugin) => {
+            plugin.fn(this, !plugin.executed, plugin.options);
+            plugin.executed = true;
+        });
+    }
+    /**
+     * Register a plugin. Plugins are called only once just before
+     * a rendering a view.
+     *
+     * You can invoke a plugin multiple times by marking it as a
+     * recurring plugin
+     */
+    use(pluginFn, options) {
+        this.#plugins.push({
+            fn: pluginFn,
+            executed: false,
+            options,
+        });
+        return this;
+    }
+    mount(diskName, viewsDirectory) {
+        if (!viewsDirectory) {
+            viewsDirectory = diskName;
+            diskName = 'default';
+        }
+        this.loader.mount(diskName, viewsDirectory);
+        return this;
+    }
+    /**
+     * Un Mount a disk from the loader.
+     *
+     * ```js
+     * edge.unmount('admin')
+     * ```
+     */
+    unmount(diskName) {
+        this.loader.unmount(diskName);
+        return this;
+    }
+    /**
+     * Add a new global to the edge globals. The globals are available
+     * to all the templates.
+     *
+     * ```js
+     * edge.global('username', 'virk')
+     * edge.global('time', () => new Date().getTime())
+     * ```
+     */
+    global(name, value) {
+        this.globals[name] = value;
+        return this;
+    }
+    /**
+     * Add a new tag to the tags list.
+     *
+     * ```ts
+     * edge.registerTag('svg', {
+     *   block: false,
+     *   seekable: true,
+     *
+     *   compile (parser, buffer, token) {
+     *     const fileName = token.properties.jsArg.trim()
+     *     buffer.writeRaw(fs.readFileSync(__dirname, 'assets', `${fileName}.svg`), 'utf-8')
+     *   }
+     * })
+     * ```
+     */
+    registerTag(tag) {
+        if (typeof tag.boot === 'function') {
+            tag.boot(template_js_1.Template);
+        }
+        this.tags[tag.tagName] = tag;
+        return this;
+    }
+    /**
+     * Register an in-memory template.
+     *
+     * ```ts
+     * edge.registerTemplate('button', {
+     *   template: `<button class="{{ this.type || 'primary' }}">
+     *     @!yield($slots.main())
+     *   </button>`,
+     * })
+     * ```
+     *
+     * Later you can use this template
+     *
+     * ```edge
+     * @component('button', type = 'primary')
+     *   Get started
+     * @endcomponent
+     * ```
+     */
+    registerTemplate(templatePath, contents) {
+        this.loader.register(templatePath, contents);
+        return this;
+    }
+    /**
+     * Remove the template registered using the "registerTemplate" method
+     */
+    removeTemplate(templatePath) {
+        this.loader.remove(templatePath);
+        this.compiler.cacheManager.delete(templatePath);
+        this.asyncCompiler.cacheManager.delete(templatePath);
+        return this;
+    }
+    /**
+     * Get access to the underlying template renderer. Each render call
+     * to edge results in creating an isolated renderer instance.
+     */
+    onRender(callback) {
+        this.#renderCallbacks.push(callback);
+        return this;
+    }
+    /**
+     * Returns a new instance of edge. The instance
+     * can be used to define locals.
+     */
+    createRenderer() {
+        this.#executePlugins();
+        const renderer = new renderer_js_1.EdgeRenderer(this.compiler, this.asyncCompiler, this.processor, this.globals);
+        this.#renderCallbacks.forEach((callback) => callback(renderer));
+        return renderer;
+    }
+    /**
+     * Render a template with optional state
+     *
+     * ```ts
+     * edge.render('welcome', { greeting: 'Hello world' })
+     * ```
+     */
+    render(templatePath, state) {
+        return this.createRenderer().render(templatePath, state);
+    }
+    /**
+     * Render a template asynchronously with optional state
+     *
+     * ```ts
+     * edge.render('welcome', { greeting: 'Hello world' })
+     * ```
+     */
+    renderSync(templatePath, state) {
+        return this.createRenderer().renderSync(templatePath, state);
+    }
+    /**
+     * Render a template with optional state
+     *
+     * ```ts
+     * edge.render('welcome', { greeting: 'Hello world' })
+     * ```
+     */
+    renderRaw(contents, state, templatePath) {
+        return this.createRenderer().renderRaw(contents, state, templatePath);
+    }
+    /**
+     * Render a template asynchronously with optional state
+     *
+     * ```ts
+     * edge.render('welcome', { greeting: 'Hello world' })
+     * ```
+     */
+    renderRawSync(templatePath, state) {
+        return this.createRenderer().renderRawSync(templatePath, state);
+    }
+    /**
+     * Share locals with the current view context.
+     *
+     * ```js
+     * const view = edge.createRenderer()
+     *
+     * // local state for the current render
+     * view.share({ foo: 'bar' })
+     *
+     * view.render('welcome')
+     * ```
+     */
+    share(data) {
+        return this.createRenderer().share(data);
+    }
+}
+exports.Edge = Edge;

package/src/edge/renderer.d.ts

@@ -0,0 +1,44 @@
+import { type Processor } from '../processor.js'
+import type { Compiler } from '../compiler.js'
+/**
+ * Renders a given template with it's shared state
+ */
+export declare class EdgeRenderer {
+  #private
+  constructor(
+    compiler: Compiler,
+    asyncCompiler: Compiler,
+    processor: Processor,
+    globals: Record<string, any>
+  )
+  /**
+   * Clone renderer instance with shared data
+   */
+  clone(): EdgeRenderer
+  /**
+   * Share local variables with the template. They will overwrite the
+   * globals
+   */
+  share(data: Record<string, any>): this
+  /**
+   * Retrieves the local and global variables, used for testing things that
+   * share variables
+   */
+  getState(): Record<string, any>
+  /**
+   * Render the template
+   */
+  render(templatePath: string, state?: Record<string, any>): Promise<string>
+  /**
+   * Render the template
+   */
+  renderSync(templatePath: string, state?: Record<string, any>): string
+  /**
+   * Render the template from a raw string
+   */
+  renderRaw(contents: string, state?: Record<string, any>, templatePath?: string): Promise<string>
+  /**
+   * Render the template from a raw string
+   */
+  renderRawSync(contents: string, state?: Record<string, any>, templatePath?: string): string
+}

package/src/edge/renderer.js

@@ -0,0 +1,85 @@
+"use strict";
+/*
+ * edge.js
+ *
+ * (c) EdgeJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EdgeRenderer = void 0;
+const lodash_1 = __importDefault(require("@poppinss/utils/lodash"));
+const template_js_1 = require("../template.js");
+/**
+ * Renders a given template with it's shared state
+ */
+class EdgeRenderer {
+    #compiler;
+    #processor;
+    #asyncCompiler;
+    /**
+     * Global state
+     */
+    #locals = {};
+    #globals;
+    constructor(compiler, asyncCompiler, processor, globals) {
+        this.#compiler = compiler;
+        this.#asyncCompiler = asyncCompiler;
+        this.#processor = processor;
+        this.#globals = globals;
+    }
+    /**
+     * Clone renderer instance with shared data
+     */
+    clone() {
+        const renderer = new EdgeRenderer(this.#compiler, this.#asyncCompiler, this.#processor, this.#globals);
+        return renderer.share(this.#locals);
+    }
+    /**
+     * Share local variables with the template. They will overwrite the
+     * globals
+     */
+    share(data) {
+        lodash_1.default.merge(this.#locals, data);
+        return this;
+    }
+    /**
+     * Retrieves the local and global variables, used for testing things that
+     * share variables
+     */
+    getState() {
+        return {
+            ...this.#globals,
+            ...this.#locals,
+        };
+    }
+    /**
+     * Render the template
+     */
+    async render(templatePath, state = {}) {
+        return new template_js_1.Template(this.#asyncCompiler, this.#globals, this.#locals, this.#processor).render(templatePath, state);
+    }
+    /**
+     * Render the template
+     */
+    renderSync(templatePath, state = {}) {
+        return new template_js_1.Template(this.#compiler, this.#globals, this.#locals, this.#processor).render(templatePath, state);
+    }
+    /**
+     * Render the template from a raw string
+     */
+    async renderRaw(contents, state = {}, templatePath) {
+        return new template_js_1.Template(this.#asyncCompiler, this.#globals, this.#locals, this.#processor).renderRaw(contents, state, templatePath);
+    }
+    /**
+     * Render the template from a raw string
+     */
+    renderRawSync(contents, state = {}, templatePath) {
+        return new template_js_1.Template(this.#compiler, this.#globals, this.#locals, this.#processor).renderRaw(contents, state, templatePath);
+    }
+}
+exports.EdgeRenderer = EdgeRenderer;

package/src/edge/stacks.d.ts

@@ -0,0 +1,22 @@
+export default class Stacks {
+  #private
+  /**
+   * Create a new stack placeholder. Multiple calls to this method
+   * with the same name results in an exception.
+   */
+  create(name: string): string
+  /**
+   * Push content inside a given stack. Content can be pre-seeded
+   * without creating a stack
+   */
+  pushTo(name: string, contents: string): this
+  /**
+   * Push contents to a stack with a unique source id. A
+   * source can only push once to a given stack.
+   */
+  pushOnceTo(name: string, sourceId: string, contents: string): void
+  /**
+   * Fill placeholders with their actual content
+   */
+  fillPlaceholders(contents: string): string
+}