edgexpress 3.0.0 → 3.0.2

package/src/types.d.ts

@@ -0,0 +1,144 @@
+/**
+ * edge
+ *
+ * (c) EdgeJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import type { TagToken } from 'edge-lexer/types'
+import type { Parser, EdgeBuffer } from 'edge-parser'
+import type { ParserTagDefinitionContract } from 'edge-parser/types'
+import type { Edge } from './edge/main.js'
+import type { Template } from './template.js'
+/**
+ * The shape in which the loader must resolve the template
+ */
+export type LoaderTemplate = {
+  template: string
+}
+export type ComponentsTree = {
+  diskName: string
+  components: {
+    componentName: string
+    tagName: string
+  }[]
+}[]
+/**
+ * Loader contract that every loader must adheres to.
+ */
+export interface LoaderContract {
+  /**
+   * List of mounted disks
+   */
+  mounted: {
+    [diskName: string]: string
+  }
+  /**
+   * List of pre-registered template
+   */
+  templates: {
+    [templatePath: string]: LoaderTemplate
+  }
+  /**
+   * Save disk name and dirPath to resolve views
+   */
+  mount(diskName: string, dirPath: string | URL): void
+  /**
+   * Remove disk from the previously saved paths
+   */
+  unmount(diskName: string): void
+  /**
+   * Resolve template contents
+   */
+  resolve(templatePath: string): LoaderTemplate
+  /**
+   * Make absolute path to a template
+   */
+  makePath(templatePath: string): string
+  /**
+   * Register in memory template and presenter
+   */
+  register(templatePath: string, contents: LoaderTemplate): void
+  /**
+   * Remove the pre-registered template
+   */
+  remove(templatePath: string): void
+  /**
+   * Returns a list of components for all the registered disks
+   */
+  listComponents(): ComponentsTree
+}
+/**
+ * The tag must have a tagName along with other properties
+ * required by lexer and parser
+ */
+export interface TagContract extends ParserTagDefinitionContract {
+  tagName: string
+  boot?(template: typeof Template): void
+}
+/**
+ * Shape of collection of tags
+ */
+export type TagsContract = {
+  [tagName: string]: TagContract
+}
+/**
+ * Shape of compiled template as a function
+ */
+export type CompiledTemplate = (
+  template: Template,
+  state: Record<string, any>,
+  $context: Record<string, any> | undefined,
+  ...localVariables: any[]
+) => any
+/**
+ * Shape of the cache manager
+ */
+export interface CacheManagerContract {
+  enabled: boolean
+  get(templatePath: string): undefined | CompiledTemplate
+  set(templatePath: string, compiledOutput: CompiledTemplate): void
+  has(templatePath: string): boolean
+  delete(templatePath: string): void
+}
+/**
+ * Compiler constructor options
+ */
+export type CompilerOptions = {
+  cache?: boolean
+  async?: boolean
+  compat?: boolean
+}
+/**
+ * Shape of options that can be passed to the
+ * edge constructor
+ */
+export type EdgeOptions = {
+  loader?: LoaderContract
+  cache?: boolean
+}
+/**
+ * Shape of edge plugin
+ */
+export type PluginFn<T> = (edge: Edge, firstRun: boolean, options: T) => void
+/**
+ * Shape of global helpers
+ */
+export type EdgeGlobals = Record<string, any>
+/**
+ * Required when creating custom tags
+ */
+export type ParserContract = Parser
+export type TagTokenContract = TagToken
+export type EdgeBufferContract = EdgeBuffer
+export type * from 'edge-lexer/types'
+export type {
+  AcornLoc,
+  ClaimTagFn,
+  MustacheTransformer,
+  OnLineFn,
+  ParserOptions,
+  ParserTagDefinitionContract,
+  TagTransformer,
+} from 'edge-parser/types'

package/src/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * edge
+ *
+ * (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 });

package/src/utils.d.ts

@@ -0,0 +1,96 @@
+import type { TagToken } from 'edge-lexer/types'
+import { type expressions as expressionsList, type Parser } from 'edge-parser'
+type ExpressionList = readonly (keyof typeof expressionsList | 'ObjectPattern' | 'ArrayPattern')[]
+/**
+ * Raise an `E_UNALLOWED_EXPRESSION` exception. Filename and expression is
+ * required to point the error stack to the correct file
+ */
+export declare function unallowedExpression(
+  message: string,
+  filename: string,
+  loc: {
+    line: number
+    col: number
+  }
+): void
+/**
+ * Validates the expression type to be part of the allowed
+ * expressions only.
+ *
+ * The filename is required to report errors.
+ *
+ * ```js
+ * isNotSubsetOf(expression, ['Literal', 'Identifier'], () => {})
+ * ```
+ */
+export declare function isSubsetOf(
+  expression: any,
+  expressions: ExpressionList,
+  errorCallback: () => void
+): void
+/**
+ * Validates the expression type not to be part of the disallowed
+ * expressions.
+ *
+ * The filename is required to report errors.
+ *
+ * ```js
+ * isNotSubsetOf(expression, 'SequenceExpression', () => {})
+ * ```
+ */
+export declare function isNotSubsetOf(
+  expression: any,
+  expressions: ExpressionList,
+  errorCallback: () => void
+): void
+/**
+ * Parses the jsArg by generating and transforming its AST
+ */
+export declare function parseJsArg(parser: Parser, token: TagToken): any
+/**
+ * Each loop. A soft replacement for `lodash.each` that we were using earlier
+ */
+export declare function each(collection: any, iteratee: (value: any, key: any) => void): void
+/**
+ * Async each loop. A soft replacement for `lodash.each` that we were
+ * using earlier with support for async await
+ */
+export declare function asyncEach(
+  collection: any,
+  iteratee: (value: any, key: any) => Promise<void>
+): Promise<void>
+/**
+ * This class generates a valid object as a string, which is written to the template
+ * output. The reason we need a string like object, since we don't want it's
+ * properties to be evaluated during the object creation, instead it must
+ * be evaluated when the compiled output is invoked.
+ */
+export declare class StringifiedObject {
+  #private
+  addSpread(key: string): void
+  /**
+   * Add key/value pair to the object.
+   *
+   * ```js
+   * stringifiedObject.add('username', `'virk'`)
+   * ```
+   */
+  add(key: any, value: any, isComputed?: boolean): void
+  /**
+   * Returns the object alike string back.
+   *
+   * ```js
+   * stringifiedObject.flush()
+   *
+   * // returns
+   * `{ username: 'virk' }`
+   * ```
+   */
+  flush(): string
+}
+/**
+ * Stringify an object to props to HTML attributes
+ */
+export declare function stringifyAttributes(props: any, namespace?: string): string
+export declare let nanoid: (length?: number) => string
+export {}

package/src/utils.js

@@ -0,0 +1,297 @@
+"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.nanoid = exports.StringifiedObject = void 0;
+exports.unallowedExpression = unallowedExpression;
+exports.isSubsetOf = isSubsetOf;
+exports.isNotSubsetOf = isNotSubsetOf;
+exports.parseJsArg = parseJsArg;
+exports.each = each;
+exports.asyncEach = asyncEach;
+exports.stringifyAttributes = stringifyAttributes;
+const classnames_1 = __importDefault(require("classnames"));
+const edge_error_1 = require("edge-error");
+const property_information_1 = require("property-information");
+/**
+ * Function to register custom properties
+ * with "property-information" package.
+ */
+function definePropertyInformation(property, value) {
+    property_information_1.html.normal[property] = property;
+    property_information_1.html.property[property] = {
+        attribute: property,
+        boolean: true,
+        property: property,
+        space: 'html',
+        booleanish: false,
+        commaOrSpaceSeparated: false,
+        commaSeparated: false,
+        spaceSeparated: false,
+        number: false,
+        overloadedBoolean: false,
+        defined: false,
+        mustUseProperty: false,
+        ...value,
+    };
+}
+definePropertyInformation('x-cloak');
+definePropertyInformation('x-ignore');
+definePropertyInformation('x-transition:enterstart', {
+    attribute: 'x-transition:enter-start',
+    property: 'x-transition:enterStart',
+    boolean: false,
+    spaceSeparated: true,
+    commaOrSpaceSeparated: true,
+});
+definePropertyInformation('x-transition:enterend', {
+    attribute: 'x-transition:enter-end',
+    property: 'x-transition:enterEnd',
+    boolean: false,
+    spaceSeparated: true,
+    commaOrSpaceSeparated: true,
+});
+definePropertyInformation('x-transition:leavestart', {
+    attribute: 'x-transition:leave-start',
+    property: 'x-transition:leaveStart',
+    boolean: false,
+    spaceSeparated: true,
+    commaOrSpaceSeparated: true,
+});
+definePropertyInformation('x-transition:leaveend', {
+    attribute: 'x-transition:leave-end',
+    property: 'x-transition:leaveEnd',
+    boolean: false,
+    spaceSeparated: true,
+    commaOrSpaceSeparated: true,
+});
+/**
+ * Alpine namespaces we handle with special
+ * rules when stringifying attributes
+ */
+const alpineNamespaces = {
+    x: 'x-',
+    xOn: 'x-on:',
+    xBind: 'x-bind:',
+    xTransition: 'x-transition:',
+};
+/**
+ * Raise an `E_UNALLOWED_EXPRESSION` exception. Filename and expression is
+ * required to point the error stack to the correct file
+ */
+function unallowedExpression(message, filename, loc) {
+    throw new edge_error_1.EdgeError(message, 'E_UNALLOWED_EXPRESSION', {
+        line: loc.line,
+        col: loc.col,
+        filename: filename,
+    });
+}
+/**
+ * Validates the expression type to be part of the allowed
+ * expressions only.
+ *
+ * The filename is required to report errors.
+ *
+ * ```js
+ * isNotSubsetOf(expression, ['Literal', 'Identifier'], () => {})
+ * ```
+ */
+function isSubsetOf(expression, expressions, errorCallback) {
+    if (!expressions.includes(expression.type)) {
+        errorCallback();
+    }
+}
+/**
+ * Validates the expression type not to be part of the disallowed
+ * expressions.
+ *
+ * The filename is required to report errors.
+ *
+ * ```js
+ * isNotSubsetOf(expression, 'SequenceExpression', () => {})
+ * ```
+ */
+function isNotSubsetOf(expression, expressions, errorCallback) {
+    if (expressions.includes(expression.type)) {
+        errorCallback();
+    }
+}
+/**
+ * Parses the jsArg by generating and transforming its AST
+ */
+function parseJsArg(parser, token) {
+    return parser.utils.transformAst(parser.utils.generateAST(token.properties.jsArg, token.loc, token.filename), token.filename, parser);
+}
+/**
+ * Each loop. A soft replacement for `lodash.each` that we were using earlier
+ */
+function each(collection, iteratee) {
+    if (Array.isArray(collection)) {
+        for (let [key, value] of collection.entries()) {
+            iteratee(value, key);
+        }
+        return;
+    }
+    if (typeof collection === 'string') {
+        let index = 0;
+        for (let value of collection) {
+            iteratee(value, index++);
+        }
+        return;
+    }
+    if (collection && typeof collection === 'object') {
+        for (let [key, value] of Object.entries(collection)) {
+            iteratee(value, key);
+        }
+    }
+}
+/**
+ * Async each loop. A soft replacement for `lodash.each` that we were
+ * using earlier with support for async await
+ */
+async function asyncEach(collection, iteratee) {
+    if (Array.isArray(collection)) {
+        for (let [key, value] of collection.entries()) {
+            await iteratee(value, key);
+        }
+        return;
+    }
+    if (typeof collection === 'string') {
+        let index = 0;
+        for (let value of collection) {
+            await iteratee(value, index++);
+        }
+        return;
+    }
+    if (collection && typeof collection === 'object') {
+        for (let [key, value] of Object.entries(collection)) {
+            await iteratee(value, key);
+        }
+    }
+}
+/**
+ * This class generates a valid object as a string, which is written to the template
+ * output. The reason we need a string like object, since we don't want it's
+ * properties to be evaluated during the object creation, instead it must
+ * be evaluated when the compiled output is invoked.
+ */
+class StringifiedObject {
+    #obj = '';
+    addSpread(key) {
+        this.#obj += this.#obj.length ? `, ${key}` : `${key}`;
+    }
+    /**
+     * Add key/value pair to the object.
+     *
+     * ```js
+     * stringifiedObject.add('username', `'virk'`)
+     * ```
+     */
+    add(key, value, isComputed = false) {
+        key = isComputed ? `[${key}]` : key;
+        this.#obj += this.#obj.length ? `, ${key}: ${value}` : `${key}: ${value}`;
+    }
+    /**
+     * Returns the object alike string back.
+     *
+     * ```js
+     * stringifiedObject.flush()
+     *
+     * // returns
+     * `{ username: 'virk' }`
+     * ```
+     */
+    flush() {
+        const obj = `{ ${this.#obj} }`;
+        this.#obj = '';
+        return obj;
+    }
+}
+exports.StringifiedObject = StringifiedObject;
+/**
+ * Stringify an object to props to HTML attributes
+ */
+function stringifyAttributes(props, namespace) {
+    const attributes = Object.keys(props);
+    if (attributes.length === 0) {
+        return '';
+    }
+    return attributes
+        .reduce((result, key) => {
+        let value = props[key];
+        key = namespace ? `${namespace}${key}` : key;
+        /**
+         * No value defined, remove attribute
+         */
+        if (!value) {
+            return result;
+        }
+        /**
+         * Handle alpine properties separately
+         */
+        if (alpineNamespaces[key] && typeof value === 'object') {
+            result = result.concat(stringifyAttributes(value, alpineNamespaces[key]));
+            return result;
+        }
+        const propInfo = (0, property_information_1.find)(property_information_1.html, key);
+        /**
+         * Ignore unknown attributes
+         */
+        if (!propInfo) {
+            return result;
+        }
+        const attribute = propInfo.attribute;
+        /**
+         * Boolean properties
+         */
+        if (value === true) {
+            result.push(attribute);
+            return result;
+        }
+        /**
+         * Encoding rules for certain properties.
+         *
+         * - Class values can be objects with conditionals
+         * - Non-booleanish and numeric properties will be html escaped
+         * - Arrays will be concatenated into a string list and html escaped
+         */
+        if (key === 'class') {
+            value = `"${(0, classnames_1.default)(value)}"`;
+        }
+        else if (Array.isArray(value)) {
+            value = `"${value.join(propInfo.commaSeparated ? ',' : ' ')}"`;
+        }
+        else {
+            value = `"${String(value)}"`;
+        }
+        /**
+         * Push attribute value string
+         */
+        result.push(`${attribute}=${value}`);
+        return result;
+    }, [])
+        .join(' ');
+}
+/**
+ * Copy-pasted from
+ * https://github.com/ai/nanoid/blob/main/nanoid.js
+ */
+const seed = 'useandom26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict';
+let nanoid = (length = 15) => {
+    let output = '';
+    const random = crypto.getRandomValues(new Uint8Array(length));
+    for (let n = 0; n < length; n++) {
+        output += seed[63 & random[n]];
+    }
+    return output;
+};
+exports.nanoid = nanoid;

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",                // modern JS target
+    "module": "CommonJS",              // Node.js module system
+    "declaration": true,               // generate .d.ts files
+    "outDir": ".",                 // compiled JS output
+    "rootDir": "./src",                 // source folder
+    "strict": true,                     // enable strict type checks
+    "esModuleInterop": true,            // allow default imports from CJS modules
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "sourceMap": false                  // set true if debugging is needed
+  },
+  "include": ["src/**/*.ts", "index.ts"],
+  "exclude": ["node_modules", "tests"]
+}