velocious 1.0.430 → 1.0.431

package/src/utils/backtrace-cleaner.js

@@ -0,0 +1,266 @@
+// @ts-check
+
+/**
+ * Runs escape reg exp.
+ * @param {string} value - Value to escape.
+ * @returns {string} - Escaped value for a RegExp pattern.
+ */
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+}
+
+/**
+ * ParsedStackFrame type.
+ * @typedef {object} ParsedStackFrame
+ * @property {string | undefined} methodName - Method/function name from the stack frame.
+ * @property {string} sourcePath - File or URL path from the stack frame.
+ * @property {number} lineNumber - Source line number.
+ * @property {number | undefined} columnNumber - Source column number.
+ */
+
+/**
+ * Runs normalize path.
+ * @param {string | undefined} value - Path or file URL.
+ * @returns {string | undefined} - Normalized path.
+ */
+function normalizePath(value) {
+  if (!value) return undefined
+
+  let normalized = value
+
+  if (normalized.startsWith("file://")) {
+    try {
+      normalized = new URL(normalized).pathname
+    } catch {
+      // Keep original value when URL parsing fails.
+    }
+  }
+
+  try {
+    normalized = decodeURIComponent(normalized)
+  } catch {
+    // Keep encoded value when decoding fails.
+  }
+
+  return normalized.replace(/\\/g, "/")
+}
+
+/**
+ * Runs normalize directory.
+ * @param {string | undefined} value - Directory path.
+ * @returns {string | undefined} - Normalized directory path ending with slash.
+ */
+function normalizeDirectory(value) {
+  const normalized = normalizePath(value)
+
+  if (!normalized) return undefined
+
+  return normalized.endsWith("/") ? normalized : `${normalized}/`
+}
+
+/**
+ * Runs parse stack frame.
+ * @param {string} line - Stack line.
+ * @returns {ParsedStackFrame | undefined} - Parsed frame when possible.
+ */
+function parseStackFrame(line) {
+  const trimmed = line.trim()
+
+  if (!trimmed.startsWith("at ")) return undefined
+
+  const frame = trimmed.slice(3)
+  const frameWithMethodMatch = frame.match(/^(.*?) \((.*)\)$/)
+  const methodName = frameWithMethodMatch ? frameWithMethodMatch[1] : undefined
+  const location = frameWithMethodMatch ? frameWithMethodMatch[2] : frame
+  const locationMatch = location.match(/^(.*):(\d+):(\d+)$/) || location.match(/^(.*):(\d+)$/)
+
+  if (!locationMatch) return undefined
+
+  const sourcePath = normalizePath(locationMatch[1])
+  const lineNumber = Number(locationMatch[2])
+  const columnNumber = locationMatch[3] === undefined ? undefined : Number(locationMatch[3])
+
+  if (!sourcePath || !Number.isFinite(lineNumber)) return undefined
+
+  return {
+    columnNumber: Number.isFinite(columnNumber) ? columnNumber : undefined,
+    lineNumber,
+    methodName,
+    sourcePath
+  }
+}
+
+/**
+ * Runs relative application path.
+ * @param {string} sourcePath - Source path.
+ * @param {string} applicationDirectory - Application directory.
+ * @returns {string} - Path relative to the application directory when possible.
+ */
+function relativeApplicationPath(sourcePath, applicationDirectory) {
+  if (sourcePath.startsWith(applicationDirectory)) {
+    return sourcePath.slice(applicationDirectory.length)
+  }
+
+  return sourcePath
+}
+
+export default class BacktraceCleaner {
+  /**
+   * Framework source directory.
+    @type {string | undefined} */
+  frameworkSourceDirectory = undefined
+
+  /**
+   * Runs get cleaned stack.
+   * @param {Error} error - Error instance.
+   * @param {object} [args] - Options object.
+   * @param {string | undefined} [args.frameworkSourceDirectory] - Directory for Velocious internals to skip.
+   * @param {boolean} [args.includeErrorHeader] - Whether to include the `Error: ...` header line.
+   * @returns {string | undefined} - The cleaned stack.
+   */
+  static getCleanedStack(error, args) {
+    return new BacktraceCleaner(error, args).getCleanedStack(args)
+  }
+
+  /**
+   * Runs get application source line.
+   * @param {Error} error - Error instance.
+   * @param {object} args - Options object.
+   * @param {string} args.applicationDirectory - Application directory.
+   * @param {string | undefined} [args.frameworkSourceDirectory] - Directory for Velocious internals to skip.
+   * @returns {string | undefined} - Source line for the first application frame.
+   */
+  static getApplicationSourceLine(error, args) {
+    return new BacktraceCleaner(error, args).getApplicationSourceLine(args)
+  }
+
+  /**
+   * Runs constructor.
+   * @param {Error} error - Error instance.
+   * @param {object} [args] - Options object.
+   * @param {string | undefined} [args.frameworkSourceDirectory] - Directory for Velocious internals to skip.
+   */
+  constructor(error, {frameworkSourceDirectory} = {}) {
+    this.error = error
+    this.frameworkSourceDirectory = normalizeDirectory(frameworkSourceDirectory)
+  }
+
+  /**
+   * Runs get cleaned stack.
+   * @param {object} [args] - Options object.
+   * @param {boolean} [args.includeErrorHeader] - Whether to include the `Error: ...` header line.
+   * @returns {string | undefined} - The cleaned stack.
+   */
+  getCleanedStack({includeErrorHeader = true} = {}) {
+    const backtrace = this.getCleanedStackLines()
+
+    if (!backtrace || backtrace.length === 0) return undefined
+
+    if (includeErrorHeader) return backtrace.join("\n")
+
+    const firstLine = backtrace[0]
+    const remainingLines = this.isErrorHeaderLine(firstLine) ? backtrace.slice(1) : backtrace
+
+    if (remainingLines.length === 0) return undefined
+
+    return remainingLines.join("\n")
+  }
+
+  /**
+   * Runs get cleaned stack lines.
+   * @returns {string[] | undefined} - Filtered stack lines.
+   */
+  getCleanedStackLines() {
+    const backtrace = this.error?.stack?.split("\n")
+
+    return backtrace?.filter((line) => this._shouldKeepStackLine(line))
+  }
+
+  /**
+   * Runs get application source line.
+   * @param {object} args - Options object.
+   * @param {string} args.applicationDirectory - Application directory.
+   * @returns {string | undefined} - Source line for the first application frame.
+   */
+  getApplicationSourceLine({applicationDirectory}) {
+    const normalizedApplicationDirectory = normalizeDirectory(applicationDirectory)
+
+    if (!normalizedApplicationDirectory) return undefined
+
+    const frame = this._firstApplicationFrame(normalizedApplicationDirectory)
+
+    if (!frame) return undefined
+
+    const relativePath = relativeApplicationPath(frame.sourcePath, normalizedApplicationDirectory)
+    const methodSuffix = frame.methodName ? `:in ${frame.methodName.replace(/^async /, "")}` : ""
+
+    return `${relativePath}:${frame.lineNumber}${methodSuffix}`
+  }
+
+  /**
+   * Runs is error header line.
+   * @param {string | undefined} line - Backtrace line.
+   * @returns {boolean} - True when the line is an error header.
+   */
+  isErrorHeaderLine(line) {
+    if (!line) return false
+
+    const trimmedLine = line.trim()
+
+    if (!trimmedLine) return false
+
+    if (trimmedLine.startsWith("Error:")) return true
+
+    const errorNamePattern = new RegExp(`^${escapeRegExp(this.error.name)}(?:\\s*\\[[^\\]]+\\])?:`)
+
+    return errorNamePattern.test(trimmedLine)
+  }
+
+  /**
+   * Runs first application frame.
+   * @param {string} applicationDirectory - Normalized application directory.
+   * @returns {ParsedStackFrame | undefined} - First app-owned frame.
+   */
+  _firstApplicationFrame(applicationDirectory) {
+    const backtrace = this.getCleanedStackLines()
+
+    if (!backtrace) return undefined
+
+    for (const line of backtrace) {
+      const frame = parseStackFrame(line)
+
+      if (!frame) continue
+      if (!frame.sourcePath.startsWith(applicationDirectory)) continue
+      if (this._frameworkSourcePath(frame.sourcePath)) continue
+
+      return frame
+    }
+
+    return undefined
+  }
+
+  /**
+   * Runs framework source path.
+   * @param {string} sourcePath - Source path.
+   * @returns {boolean} - Whether the path belongs to Velocious internals.
+   */
+  _frameworkSourcePath(sourcePath) {
+    if (!this.frameworkSourceDirectory) return false
+
+    return sourcePath.startsWith(this.frameworkSourceDirectory)
+  }
+
+  /**
+   * Runs should keep stack line.
+   * @param {string} line - Stack line.
+   * @returns {boolean} - Whether to keep the stack line.
+   */
+  _shouldKeepStackLine(line) {
+    if (line.includes("node_modules")) return false
+    if (line.includes("(node:internal/")) return false
+    if (line.includes("(node:internal/process/")) return false
+    if (line.trim().startsWith("at node:internal/")) return false
+
+    return true
+  }
+}

package/src/utils/ensure-error.js

@@ -0,0 +1,15 @@
+// @ts-check
+
+/**
+ * Runs ensure error.
+ * @param {?} error - Error instance.
+ * @returns {Error} - The error.
+ */
+export default function ensureError(error) {
+  if (error instanceof Error) {
+    return error
+  } else {
+    return new Error(`Unknown error type ${typeof error}: ${error}`)
+  }
+}
+

package/src/utils/event-emitter.js

@@ -0,0 +1,8 @@
+// @ts-check
+
+import EventEmitterDefault from "eventemitter3"
+
+/** @type {typeof import("eventemitter3").EventEmitter} */
+const EventEmitter = /** @type {?} */ (EventEmitterDefault)
+
+export default EventEmitter

package/src/utils/file-exists.js

@@ -0,0 +1,18 @@
+// @ts-check
+
+import fs from "fs/promises"
+
+/**
+ * Runs file exists.
+ * @param {string} path - Path.
+ * @returns {Promise<boolean>} - Resolves with Whether the operation succeeded.
+ */
+export default async function fileExists(path) {
+  try {
+    await fs.access(path)
+
+    return true
+  } catch (error) { // eslint-disable-line no-unused-vars
+    return false
+  }
+}

package/src/utils/format-value.js

@@ -0,0 +1,101 @@
+// @ts-check
+
+const MAX_STRINGIFY_DEPTH = 5
+
+/**
+ * Runs is plain object.
+ * @param {?} value - Value to use.
+ * @returns {boolean} - Whether plain object.
+ */
+function isPlainObject(value) {
+  if (!value || typeof value != "object") return false
+
+  const prototype = Object.getPrototypeOf(value)
+
+  return prototype === Object.prototype || prototype === null
+}
+
+/**
+ * Minified stringify with circular and depth protection.
+ * @param {?} value - Value to use.
+ * @returns {string} - The minified stringify.
+ */
+function minifiedStringify(value) {
+  const seen = new WeakSet()
+
+  /**
+   * Runs serialize.
+   * @param {?} current - Current.
+   * @param {number} depth - Depth.
+   * @returns {?} - The serialize.
+   */
+  function serialize(current, depth) {
+    if (depth > MAX_STRINGIFY_DEPTH) return "[MaxDepth]"
+    if (!current || typeof current != "object") return current
+
+    if (seen.has(current)) return "[Circular]"
+
+    if (current instanceof Set) {
+      return Array.from(current).map((value) => serialize(value, depth + 1))
+    }
+
+    if (!isPlainObject(current) && !Array.isArray(current)) {
+      return current.constructor?.name || Object.prototype.toString.call(current)
+    }
+
+    seen.add(current)
+
+    if (Array.isArray(current)) {
+      return current.map(value => serialize(value, depth + 1))
+    }
+
+    /**
+     * Output.
+      @type {Record<string, ?>} */
+    const output = {}
+
+    for (const key of Object.keys(current)) {
+      output[key] = serialize(current[key], depth + 1)
+    }
+
+    return output
+  }
+
+  try {
+    return JSON.stringify(serialize(value, 0))
+  } catch {
+    return String(value)
+  }
+}
+
+/**
+ * Runs format value.
+ * @param {?} value - Value to use.
+ * @returns {string} - The value.
+ */
+function formatValue(value) {
+  if (value === undefined) return "undefined"
+  if (value === null) return "null"
+  if (typeof value == "string") return value
+  if (typeof value == "number" || typeof value == "boolean" || typeof value == "bigint") return String(value)
+  if (typeof value == "symbol") return value.toString()
+  if (typeof value == "function") return value.name || "function"
+
+  if (Array.isArray(value) || isPlainObject(value)) {
+    return minifiedStringify(value)
+  }
+
+  if (value instanceof Set) {
+    return `Set(${minifiedStringify(Array.from(value))})`
+  }
+
+  if (value && typeof value == "object") {
+    const constructorName = value.constructor?.name
+
+    if (constructorName) return constructorName
+  }
+
+  return String(value)
+}
+
+export {formatValue, minifiedStringify}

package/src/utils/model-scope.js

@@ -0,0 +1,56 @@
+// @ts-check
+
+const MODEL_SCOPE_DESCRIPTOR_MARKER = "velociousModelScopeDescriptor"
+
+/**
+ * ModelScopeDescriptor type.
+ * @typedef {object} ModelScopeDescriptor
+ * @property {true} [velociousModelScopeDescriptor] - Internal marker.
+ * @property {(...args: Array<?>) => ?} callback - Scope callback.
+ * @property {typeof import("../database/record/index.js").default | typeof import("../frontend-models/base.js").default} modelClass - Owning model class.
+ * @property {Array<?>} scopeArgs - Scope arguments.
+ */
+
+/**
+ * Runs the defineModelScope helper.
+ * @param {object} args - Definition arguments.
+ * @param {(...args: Array<?>) => ?} args.callback - Scope callback.
+ * @param {typeof import("../database/record/index.js").default | typeof import("../frontend-models/base.js").default} args.modelClass - Owning model class.
+ * @param {() => ?} args.startQuery - Factory that returns a fresh query for the owning model class.
+ * @returns {((...args: Array<?>) => ?) & {scope: (...args: Array<?>) => ModelScopeDescriptor}} - Scope helper.
+ */
+export function defineModelScope({callback, modelClass, startQuery}) {
+  /**
+   * Runs defined scope.
+   * @param {...?} scopeArgs - Scope arguments.
+   * @returns {?} - Scoped root query.
+   */
+  function definedScope(...scopeArgs) {
+    return startQuery().scope(definedScope.scope(...scopeArgs))
+  }
+
+  /**
+   * Builds a reusable scope descriptor.
+   * @param {...?} scopeArgs - Scope arguments.
+   * @returns {ModelScopeDescriptor} - Reusable scope descriptor.
+   */
+  definedScope.scope = (...scopeArgs) => ({
+    [MODEL_SCOPE_DESCRIPTOR_MARKER]: true,
+    callback,
+    modelClass,
+    scopeArgs
+  })
+
+  return definedScope
+}
+
+/**
+ * Runs the isModelScopeDescriptor helper.
+ * @param {?} value - Candidate descriptor.
+ * @returns {value is ModelScopeDescriptor} - Whether the value is a scope descriptor.
+ */
+export function isModelScopeDescriptor(value) {
+  return Boolean(value && typeof value === "object" && /**
+                                                        * Narrows the runtime value to the documented type.
+                                                         @type {Record<string, ?>} */ (value)[MODEL_SCOPE_DESCRIPTOR_MARKER] === true)
+}

package/src/utils/nest-callbacks.js

@@ -0,0 +1,22 @@
+/**
+ * Runs nest callbacks.
+ * @param {Array<(next: () => Promise<void>) => void | Promise<void>>} callbacksToNestInside - Callbacks to nest inside.
+ * @param {() => void | Promise<void>} callback - Callback function.
+ * @returns {Promise<void>} - Resolves when complete.
+ */
+export default async function nestCallbacks(callbacksToNestInside, callback) {
+  const baseCallback = async () => { await callback() }
+  let runCallback = baseCallback
+
+  for (const callbackToNestInside of callbacksToNestInside) {
+    const actualRunCallback = runCallback
+
+    const nextRunRequest = async () => {
+      await callbackToNestInside(actualRunCallback)
+    }
+
+    runCallback = nextRunRequest
+  }
+
+  await runCallback()
+}

package/src/utils/plain-object.js

@@ -0,0 +1,14 @@
+// @ts-check
+
+/**
+ * Detect plain object literals without accepting arrays or class instances.
+ * @param {?} value - Candidate value.
+ * @returns {value is Record<string, ?>} - Whether value is a plain object.
+ */
+export default function isPlainObject(value) {
+  if (Object.prototype.toString.call(value) !== "[object Object]") return false
+
+  const prototype = Object.getPrototypeOf(value)
+
+  return prototype === Object.prototype || prototype === null
+}