edgexpress 3.0.0 → 3.0.2

package/src/tags/push_once_to.js

@@ -0,0 +1,65 @@
+"use strict";
+/*
+ * edge.js
+ *
+ * (c) Harminder Virk
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pushOnceToTag = void 0;
+const edge_error_1 = require("edge-error");
+const edge_parser_1 = require("edge-parser");
+const utils_js_1 = require("../utils.js");
+/**
+ * Stack tag to define stack placeholders
+ */
+exports.pushOnceToTag = {
+    tagName: 'pushOnceTo',
+    block: true,
+    seekable: true,
+    noNewLine: true,
+    generateId() {
+        return `stack_${(0, utils_js_1.nanoid)()}`;
+    },
+    compile(parser, buffer, token) {
+        const parsed = parser.utils.transformAst(parser.utils.generateAST(token.properties.jsArg, token.loc, token.filename), token.filename, parser);
+        /**
+         * Disallow sequence expressions
+         */
+        if (edge_parser_1.expressions.SequenceExpression.includes(parsed.type)) {
+            throw new edge_error_1.EdgeError(`"${token.properties.jsArg}" is not a valid argument type for the "@pushOnceTo" tag`, 'E_UNALLOWED_EXPRESSION', {
+                ...parser.utils.getExpressionLoc(parsed),
+                filename: token.filename,
+            });
+        }
+        /**
+         * Each stack must be unique
+         */
+        const stackId = this.generateId();
+        /**
+         * Create a custom buffer for the stack. Since we do not want to the write
+         * to the main buffer
+         */
+        const stackBuffer = buffer.create(token.filename, { outputVar: stackId });
+        /**
+         * Process children
+         */
+        for (let child of token.children) {
+            parser.processToken(child, stackBuffer);
+        }
+        /**
+         * Flush the stack buffer content to the main buffer
+         */
+        buffer.writeStatement(stackBuffer
+            .disableFileAndLineVariables()
+            .disableReturnStatement()
+            .disableTryCatchBlock()
+            .flush(), token.filename, token.loc.start.line);
+        const { line, col } = token.loc.start;
+        const normalizedFileName = token.filename.replace(/\\|\//g, '_');
+        const sourceId = `${normalizedFileName}-${line}-${col}`;
+        buffer.writeExpression(`template.stacks.pushOnceTo(${parser.utils.stringify(parsed)}, '${sourceId}', ${stackId})`, token.filename, line);
+    },
+};

package/src/tags/push_to.d.ts

@@ -0,0 +1,7 @@
+import { type TagContract } from '../types.js'
+/**
+ * Stack tag to define stack placeholders
+ */
+export declare const pushToTag: TagContract & {
+  generateId(): string
+}

package/src/tags/push_to.js

@@ -0,0 +1,62 @@
+"use strict";
+/*
+ * edge.js
+ *
+ * (c) Harminder Virk
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pushToTag = void 0;
+const edge_error_1 = require("edge-error");
+const edge_parser_1 = require("edge-parser");
+const utils_js_1 = require("../utils.js");
+/**
+ * Stack tag to define stack placeholders
+ */
+exports.pushToTag = {
+    tagName: 'pushTo',
+    block: true,
+    seekable: true,
+    noNewLine: true,
+    generateId() {
+        return `stack_${(0, utils_js_1.nanoid)()}`;
+    },
+    compile(parser, buffer, token) {
+        const parsed = parser.utils.transformAst(parser.utils.generateAST(token.properties.jsArg, token.loc, token.filename), token.filename, parser);
+        /**
+         * Disallow sequence expressions
+         */
+        if (edge_parser_1.expressions.SequenceExpression.includes(parsed.type)) {
+            throw new edge_error_1.EdgeError(`"${token.properties.jsArg}" is not a valid argument type for the "@pushTo" tag`, 'E_UNALLOWED_EXPRESSION', {
+                ...parser.utils.getExpressionLoc(parsed),
+                filename: token.filename,
+            });
+        }
+        /**
+         * Each stack must be unique
+         */
+        const stackId = this.generateId();
+        /**
+         * Create a custom buffer for the stack. Since we do not want to the write
+         * to the main buffer
+         */
+        const stackBuffer = buffer.create(token.filename, { outputVar: stackId });
+        /**
+         * Process children
+         */
+        for (let child of token.children) {
+            parser.processToken(child, stackBuffer);
+        }
+        /**
+         * Flush the stack buffer content to the main buffer
+         */
+        buffer.writeStatement(stackBuffer
+            .disableFileAndLineVariables()
+            .disableReturnStatement()
+            .disableTryCatchBlock()
+            .flush(), token.filename, token.loc.start.line);
+        buffer.writeExpression(`template.stacks.pushTo(${parser.utils.stringify(parsed)}, ${stackId})`, token.filename, token.loc.start.line);
+    },
+};

package/src/tags/slot.d.ts

@@ -0,0 +1,6 @@
+import { type TagContract } from '../types.js'
+/**
+ * Slot tag is used to define the slots of a given component. Slots cannot be
+ * nested and must appear as top level children inside a component.
+ */
+export declare const slotTag: TagContract

package/src/tags/slot.js

@@ -0,0 +1,29 @@
+"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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.slotTag = void 0;
+const edge_error_1 = require("edge-error");
+/**
+ * Slot tag is used to define the slots of a given component. Slots cannot be
+ * nested and must appear as top level children inside a component.
+ */
+exports.slotTag = {
+    block: true,
+    seekable: true,
+    tagName: 'slot',
+    noNewLine: true,
+    compile(_, __, token) {
+        throw new edge_error_1.EdgeError('@slot tag must appear as top level tag inside the @component tag', 'E_ORPHAN_SLOT_TAG', {
+            line: token.loc.start.line,
+            col: token.loc.start.col,
+            filename: token.filename,
+        });
+    },
+};

package/src/tags/stack.d.ts

@@ -0,0 +1,5 @@
+import { type TagContract } from '../types.js'
+/**
+ * Stack tag to define stack placeholders
+ */
+export declare const stackTag: TagContract

package/src/tags/stack.js

@@ -0,0 +1,38 @@
+"use strict";
+/*
+ * edge.js
+ *
+ * (c) Harminder Virk
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stackTag = void 0;
+const edge_error_1 = require("edge-error");
+const edge_parser_1 = require("edge-parser");
+/**
+ * Stack tag to define stack placeholders
+ */
+exports.stackTag = {
+    tagName: 'stack',
+    block: false,
+    seekable: true,
+    noNewLine: false,
+    compile(parser, buffer, token) {
+        const parsed = parser.utils.transformAst(parser.utils.generateAST(token.properties.jsArg, token.loc, token.filename), token.filename, parser);
+        /**
+         * Disallow sequence expressions
+         */
+        if (edge_parser_1.expressions.SequenceExpression.includes(parsed.type)) {
+            throw new edge_error_1.EdgeError(`"${token.properties.jsArg}" is not a valid argument type for the "@stack" tag`, 'E_UNALLOWED_EXPRESSION', {
+                ...parser.utils.getExpressionLoc(parsed),
+                filename: token.filename,
+            });
+        }
+        /**
+         * Create stack
+         */
+        buffer.outputExpression(`template.stacks.create(${parser.utils.stringify(parsed)})`, token.filename, token.loc.start.line, false);
+    },
+};

package/src/tags/unless.d.ts

@@ -0,0 +1,12 @@
+import { type TagContract } from '../types.js'
+/**
+ * Inverse of the `if` condition. The term `unless` is more readable and logical
+ * vs using `@if(!expression)`.
+ *
+ * ```edge
+ * @unless(auth.user)
+ *   <a href="/login"> Login </a>
+ * @endunless
+ * ```
+ */
+export declare const unlessTag: TagContract

package/src/tags/unless.js

@@ -0,0 +1,52 @@
+"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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unlessTag = void 0;
+const edge_parser_1 = require("edge-parser");
+const utils_js_1 = require("../utils.js");
+/**
+ * Inverse of the `if` condition. The term `unless` is more readable and logical
+ * vs using `@if(!expression)`.
+ *
+ * ```edge
+ * @unless(auth.user)
+ *   <a href="/login"> Login </a>
+ * @endunless
+ * ```
+ */
+exports.unlessTag = {
+    block: true,
+    seekable: true,
+    tagName: 'unless',
+    /**
+     * Compiles the if block node to a Javascript if statement
+     */
+    compile(parser, buffer, token) {
+        const parsed = (0, utils_js_1.parseJsArg)(parser, token);
+        /**
+         * Disallow sequence expressions
+         */
+        (0, utils_js_1.isNotSubsetOf)(parsed, [edge_parser_1.expressions.SequenceExpression], () => {
+            (0, utils_js_1.unallowedExpression)(`"${token.properties.jsArg}" is not a valid argument type for the @unless tag`, token.filename, parser.utils.getExpressionLoc(parsed));
+        });
+        /**
+         * Start if block
+         */
+        buffer.writeStatement(`if (!${parser.utils.stringify(parsed)}) {`, token.filename, token.loc.start.line);
+        /**
+         * Process of all children recursively
+         */
+        token.children.forEach((child) => parser.processToken(child, buffer));
+        /**
+         * Close if block
+         */
+        buffer.writeStatement('}', token.filename, -1);
+    },
+};

package/src/template.d.ts

@@ -0,0 +1,127 @@
+import Macroable from '@poppinss/macroable'
+import type Stacks from './edge/stacks.js'
+import { type Compiler } from './compiler.js'
+import { type Processor } from './processor.js'
+import { type Props } from './migrate/props.js'
+import type { CompiledTemplate } from './types.js'
+import { type ComponentProps } from './component/props.js'
+/**
+ * An instance of this class passed to the escape
+ * method ensures that underlying value is never
+ * escaped.
+ */
+declare class SafeValue {
+  value: any
+  constructor(value: any)
+}
+/**
+ * Escapes a given string
+ */
+export declare function escape(input: any): string
+/**
+ * Mark value as safe and not to be escaped
+ */
+export declare function htmlSafe(value: string): SafeValue
+/**
+ * The template is used to compile and run templates. Also the instance
+ * of template is passed during runtime to render `dynamic partials`
+ * and `dynamic components`.
+ */
+export declare class Template extends Macroable {
+  #private
+  /**
+   * Template stacks holds a collection of placeholders
+   * and their content to be filled before returning
+   * the output.
+   */
+  stacks: Stacks
+  constructor(compiler: Compiler, globals: any, locals: any, processor: Processor)
+  /**
+   * Render a partial
+   *
+   * ```js
+   * const partialFn = template.compilePartial('includes/user')
+   *
+   * // render and use output
+   * partialFn(template, state, ctx)
+   * ```
+   */
+  compilePartial(templatePath: string, ...localVariables: string[]): CompiledTemplate
+  /**
+   * Render a component
+   *
+   * ```js
+   * const componentFn = template.compileComponent('components/button')
+   *
+   * // render and use output
+   * componentFn(template, template.getComponentState(props, slots, caller), ctx)
+   * ```
+   */
+  compileComponent(templatePath: string): CompiledTemplate
+  /**
+   * Returns the isolated state for a given component
+   */
+  getComponentState(
+    props: {
+      [key: string]: any
+    },
+    slots: {
+      [key: string]: any
+    },
+    caller: {
+      filename: string
+      line: number
+      col: number
+    }
+  ): {
+    $slots: {
+      [key: string]: any
+    }
+    $caller: {
+      filename: string
+      line: number
+      col: number
+    }
+    $props: ComponentProps | Props
+  }
+  /**
+   * Render a template with it's state.
+   *
+   * ```js
+   * template.render('welcome', { key: 'value' })
+   * ```
+   */
+  render<T extends Promise<string> | string>(template: string, state: any): T
+  /**
+   * Render template from a raw string
+   *
+   * ```js
+   * template.renderRaw('Hello {{ username }}', { username: 'virk' })
+   * ```
+   */
+  renderRaw<T extends Promise<string> | string>(
+    contents: string,
+    state: any,
+    templatePath?: string
+  ): T
+  /**
+   * Escapes the value to be HTML safe. Only strings are escaped
+   * and rest all values will be returned as it is.
+   */
+  escape(input: any): string
+  /**
+   * Creates an instance of the EdgeError
+   */
+  createError(errorMessage: string, filename: string, lineNumber: number, column: number): any
+  /**
+   * Throws EdgeError. Use "createError" to create a new
+   * error instance
+   */
+  newError(errorMessage: string, filename: string, lineNumber: number, column: number): void
+  /**
+   * Rethrows the runtime exception by re-constructing the error message
+   * to point back to the original filename
+   */
+  reThrow(error: any, filename: string, lineNumber: number): never
+}
+export {}

package/src/template.js

@@ -0,0 +1,203 @@
+"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.Template = void 0;
+exports.escape = escape;
+exports.htmlSafe = htmlSafe;
+const he_1 = __importDefault(require("he"));
+const edge_error_1 = require("edge-error");
+const lodash_1 = __importDefault(require("@poppinss/utils/lodash"));
+const macroable_1 = __importDefault(require("@poppinss/macroable"));
+const stacks_js_1 = __importDefault(require("./edge/stacks.js"));
+const props_js_1 = require("./migrate/props.js");
+const props_js_2 = require("./component/props.js");
+/**
+ * An instance of this class passed to the escape
+ * method ensures that underlying value is never
+ * escaped.
+ */
+class SafeValue {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+}
+/**
+ * Escapes a given string
+ */
+function escape(input) {
+    return input instanceof SafeValue ? input.value : he_1.default.escape(String(input));
+}
+/**
+ * Mark value as safe and not to be escaped
+ */
+function htmlSafe(value) {
+    return new SafeValue(value);
+}
+/**
+ * The template is used to compile and run templates. Also the instance
+ * of template is passed during runtime to render `dynamic partials`
+ * and `dynamic components`.
+ */
+class Template extends macroable_1.default {
+    #compiler;
+    #processor;
+    /**
+     * The shared state is used to hold the globals and locals,
+     * since it is shared with components too.
+     */
+    #sharedState;
+    /**
+     * Template stacks holds a collection of placeholders
+     * and their content to be filled before returning
+     * the output.
+     */
+    stacks = new stacks_js_1.default();
+    constructor(compiler, globals, locals, processor) {
+        super();
+        this.#compiler = compiler;
+        this.#processor = processor;
+        this.#sharedState = compiler.compat
+            ? lodash_1.default.merge({}, globals, locals)
+            : {
+                ...globals,
+                ...locals,
+            };
+    }
+    /**
+     * Trims top and bottom new lines from the content
+     */
+    #trimTopBottomNewLines(value) {
+        return value.replace(/^\n|^\r\n/, '').replace(/\n$|\r\n$/, '');
+    }
+    /**
+     * Render a compiled template with state
+     */
+    #renderCompiled(compiledTemplate, state) {
+        const templateState = { ...this.#sharedState, ...state };
+        const $context = {};
+        /**
+         * Process template as a promise.
+         */
+        if (this.#compiler.async) {
+            return compiledTemplate(this, templateState, $context).then((output) => {
+                output = this.#trimTopBottomNewLines(output);
+                output = this.stacks.fillPlaceholders(output);
+                return this.#processor.executeOutput({ output, template: this, state: templateState });
+            });
+        }
+        let output = this.#trimTopBottomNewLines(compiledTemplate(this, templateState, $context));
+        output = this.stacks.fillPlaceholders(output);
+        return this.#processor.executeOutput({ output, template: this, state: templateState });
+    }
+    /**
+     * Render a partial
+     *
+     * ```js
+     * const partialFn = template.compilePartial('includes/user')
+     *
+     * // render and use output
+     * partialFn(template, state, ctx)
+     * ```
+     */
+    compilePartial(templatePath, ...localVariables) {
+        return this.#compiler.compile(templatePath, localVariables);
+    }
+    /**
+     * Render a component
+     *
+     * ```js
+     * const componentFn = template.compileComponent('components/button')
+     *
+     * // render and use output
+     * componentFn(template, template.getComponentState(props, slots, caller), ctx)
+     * ```
+     */
+    compileComponent(templatePath) {
+        return this.#compiler.compile(templatePath);
+    }
+    /**
+     * Returns the isolated state for a given component
+     */
+    getComponentState(props, slots, caller) {
+        return {
+            ...this.#sharedState,
+            ...props,
+            $slots: slots,
+            $caller: caller,
+            $props: this.#compiler.compat ? new props_js_1.Props(props) : new props_js_2.ComponentProps(props),
+        };
+    }
+    /**
+     * Render a template with it's state.
+     *
+     * ```js
+     * template.render('welcome', { key: 'value' })
+     * ```
+     */
+    render(template, state) {
+        let compiledTemplate = this.#compiler.compile(template);
+        return this.#renderCompiled(compiledTemplate, state);
+    }
+    /**
+     * Render template from a raw string
+     *
+     * ```js
+     * template.renderRaw('Hello {{ username }}', { username: 'virk' })
+     * ```
+     */
+    renderRaw(contents, state, templatePath) {
+        let compiledTemplate = this.#compiler.compileRaw(contents, templatePath);
+        return this.#renderCompiled(compiledTemplate, state);
+    }
+    /**
+     * Escapes the value to be HTML safe. Only strings are escaped
+     * and rest all values will be returned as it is.
+     */
+    escape(input) {
+        return escape(input);
+    }
+    /**
+     * Creates an instance of the EdgeError
+     */
+    createError(errorMessage, filename, lineNumber, column) {
+        return new edge_error_1.EdgeError(errorMessage, 'E_RUNTIME_EXCEPTION', {
+            filename: filename,
+            line: lineNumber,
+            col: column,
+        });
+    }
+    /**
+     * Throws EdgeError. Use "createError" to create a new
+     * error instance
+     */
+    newError(errorMessage, filename, lineNumber, column) {
+        throw this.createError(errorMessage, filename, lineNumber, column);
+    }
+    /**
+     * Rethrows the runtime exception by re-constructing the error message
+     * to point back to the original filename
+     */
+    reThrow(error, filename, lineNumber) {
+        if (error instanceof edge_error_1.EdgeError) {
+            throw error;
+        }
+        const message = error.message.replace(/state\./, '');
+        throw new edge_error_1.EdgeError(message, 'E_RUNTIME_EXCEPTION', {
+            filename: filename,
+            line: lineNumber,
+            col: 0,
+        });
+    }
+}
+exports.Template = Template;