velocious 1.0.430 → 1.0.431

package/src/mailer/base.js

@@ -0,0 +1,337 @@
+// @ts-check
+
+import ejs from "ejs"
+import {incorporate} from "incorporator"
+import * as inflection from "inflection"
+import configurationResolver from "../configuration-resolver.js"
+import restArgsError from "../utils/rest-args-error.js"
+import MailerDelivery from "./delivery.js"
+
+/**
+ * Deliveries store.
+  @type {import("./index.js").MailerDeliveryPayload[]} */
+const deliveriesStore = []
+/**
+ * Delivery handler.
+  @type {((payload: import("./index.js").MailerDeliveryPayload) => Promise<?> | ?) | null} */
+let deliveryHandler = null
+
+/**
+ * Runs view file name.
+ * @param {string} actionName - Mailer action name.
+ * @returns {string} - View file name.
+ */
+function viewFileName(actionName) {
+  return inflection.dasherize(inflection.underscore(actionName))
+}
+
+/**
+ * Runs mailer directory name.
+ * @param {string} className - Mailer class name.
+ * @returns {string} - Mailer directory name.
+ */
+function mailerDirectoryName(className) {
+  const baseName = className.replace(/Mailer$/, "")
+
+  return inflection.dasherize(inflection.underscore(baseName))
+}
+
+/**
+ * Runs the inferActionName helper.
+ * @param {typeof VelociousMailerBase} mailerClass - Mailer class.
+ * @param {string} stack - Error stack.
+ * @returns {string | null} - Inferred action name.
+ */
+// fallow-ignore-next-line complexity
+function inferActionName(mailerClass, stack) {
+  const prototype = mailerClass.prototype
+  let actionName = null
+
+  for (const line of stack.split("\n")) {
+    const match = line.match(/\bat (?:async )?(?:new )?[^\s.]+\.([^\s.]+) /)
+
+    if (!match) continue
+
+    const frameActionName = match[1]
+
+    if (frameActionName === "mail") continue
+    if (frameActionName.startsWith("_")) continue
+    if (frameActionName === "constructor") continue
+    if (Object.prototype.hasOwnProperty.call(VelociousMailerBase.prototype, frameActionName)) continue
+    if (typeof /**
+                * Narrows the runtime value to the documented type.
+                 @type {Record<string, ?>} */ (/**
+                                                * Narrows the runtime value to the documented type.
+                                                 @type {?} */ (prototype))[frameActionName] !== "function") continue
+
+    actionName = frameActionName
+  }
+
+  return actionName
+}
+
+/**
+ * Runs is testing environment.
+ * @returns {Promise<boolean>} - Whether the current environment is test.
+ */
+async function isTestingEnvironment() {
+  const configuration = await configurationResolver()
+
+  return configuration.getEnvironment() === "test"
+}
+
+/**
+ * Base mailer with view rendering and delivery helpers.
+ */
+export class VelociousMailerBase {
+  /**
+   * Runs constructor.
+   * @param {object} [args] - Constructor args.
+   * @param {import("../configuration.js").default} [args.configuration] - Configuration instance.
+   */
+  constructor({configuration} = {}) {
+    this._actionName = null
+    this._mailOptions = null
+    this._viewParams = {}
+    this._configurationPromise = configuration ? Promise.resolve(configuration) : configurationResolver()
+  }
+
+  /**
+   * Runs assign view.
+   * @param {Record<string, ?>} params - View params.
+   * @returns {void} - No return value.
+   */
+  assignView(params) {
+    this._viewParams = Object.assign(this._viewParams, params || {})
+  }
+
+  /**
+   * Runs mail.
+   * @param {object} args - Mail options.
+   * @param {?} args.to - Recipient.
+   * @param {string} args.subject - Subject line.
+   * @param {?} [args.from] - Sender.
+   * @param {?} [args.cc] - CC recipients.
+   * @param {?} [args.bcc] - BCC recipients.
+   * @param {?} [args.replyTo] - Reply-to address.
+   * @param {Record<string, string>} [args.headers] - Custom headers.
+   * @param {string} [args.actionName] - Mailer action name.
+   * @param {Promise<?> | ?} [args.actionPromise] - Action completion promise.
+   * @returns {MailerDelivery} - Delivery wrapper.
+   */
+  mail({to, subject, from, cc, bcc, replyTo, headers, actionName, actionPromise, ...restArgs}) {
+    restArgsError(restArgs)
+
+    const resolvedActionName = actionName || inferActionName(/**
+                                                              * Narrows the runtime value to the documented type.
+                                                               @type {typeof VelociousMailerBase} */ (this.constructor), new Error().stack || "")
+
+    if (!resolvedActionName) {
+      throw new Error(`Missing actionName for ${this.constructor.name}.mail()`)
+    }
+
+    this._actionName = resolvedActionName
+    this._mailOptions = {to, subject, from, cc, bcc, replyTo, headers}
+    const resolvedActionPromise = actionPromise === undefined ? Promise.resolve() : Promise.resolve(actionPromise)
+
+    return new MailerDelivery({
+      mailer: this,
+      actionPromise: resolvedActionPromise,
+      actionName: resolvedActionName
+    })
+  }
+
+  /**
+   * Runs get configuration.
+   * @returns {Promise<import("../configuration.js").default>} - Configuration instance.
+   */
+  async _getConfiguration() {
+    return await this._configurationPromise
+  }
+
+  /**
+   * Runs get action name.
+   * @returns {string} - Action name.
+   */
+  _getActionName() {
+    if (!this._actionName) {
+      throw new Error(`No mailer action set on ${this.constructor.name}`)
+    }
+
+    return this._actionName
+  }
+
+  /**
+   * Runs build payload sync.
+   * @param {string} html - Rendered HTML.
+   * @returns {import("./index.js").MailerDeliveryPayload} - Delivery payload.
+   */
+  _buildPayloadSync(html) {
+    const mailOptions = this._mailOptions
+
+    if (!mailOptions) {
+      throw new Error(`Missing mail() options for ${this.constructor.name}#${this._getActionName()}. Got: ${String(mailOptions)}`)
+    }
+
+    if (!mailOptions.to) {
+      throw new Error(`Missing "to" for ${this.constructor.name}#${this._getActionName()}. Got: ${String(mailOptions.to)}`)
+    }
+
+    if (!mailOptions.subject) {
+      throw new Error(`Missing "subject" for ${this.constructor.name}#${this._getActionName()}. Got: ${String(mailOptions.subject)}`)
+    }
+
+    return {
+      to: mailOptions.to,
+      subject: mailOptions.subject,
+      from: mailOptions.from,
+      cc: mailOptions.cc,
+      bcc: mailOptions.bcc,
+      replyTo: mailOptions.replyTo,
+      headers: mailOptions.headers,
+      html,
+      mailer: this.constructor.name,
+      action: this._getActionName()
+    }
+  }
+
+  /**
+   * Runs build payload.
+   * @returns {Promise<import("./index.js").MailerDeliveryPayload>} - Delivery payload.
+   */
+  async _buildPayload() {
+    const html = await this._renderView()
+
+    return this._buildPayloadSync(html)
+  }
+
+  /**
+   * Runs render view.
+   * @returns {Promise<string>} - Rendered HTML.
+   */
+  async _renderView() {
+    const configuration = await this._getConfiguration()
+    const mailerDir = mailerDirectoryName(this.constructor.name)
+    const actionName = this._getActionName()
+    const fileName = viewFileName(actionName)
+    const viewPath = `${configuration.getDirectory()}/src/mailers/${mailerDir}/${fileName}.ejs`
+    const translate = (/**
+                        * Narrows the runtime value to the documented type.
+                         @type {string} */ msgID, /**
+                                                   * Narrows the runtime value to the documented type.
+                                                    @type {Record<string, ?> | undefined} */ args) => configuration.getTranslator()(msgID, args)
+    const viewParams = incorporate({mailer: this, _: translate}, this._viewParams)
+
+    return await new Promise((resolve, reject) => {
+      ejs.renderFile(viewPath, viewParams, {}, (err, str) => {
+        if (err) {
+          const errorCode = /**
+                             * Narrows the runtime value to the documented type.
+                              @type {{code?: string}} */ (err).code
+
+          if (errorCode === "ENOENT") {
+            reject(new Error(`Missing mailer view file: ${viewPath}`))
+          } else {
+            reject(err)
+          }
+        } else {
+          resolve(str)
+        }
+      })
+    })
+  }
+
+  /**
+   * Runs deliver payload.
+   * @param {import("./index.js").MailerDeliveryPayload} payload - Mail delivery payload.
+   * @returns {Promise<import("./index.js").MailerDeliveryPayload | ?>} - Handler result.
+   */
+  async _deliverPayload(payload) {
+    return await deliverPayload(payload)
+  }
+
+  /**
+   * Runs enqueue payload.
+   * @param {import("./index.js").MailerDeliveryPayload} payload - Mail delivery payload.
+   * @returns {Promise<string | import("./index.js").MailerDeliveryPayload | null>} - Job id or payload in test mode.
+   */
+  async _enqueuePayload(payload) {
+    return await enqueuePayload(payload)
+  }
+}
+
+/**
+ * Runs the deliveries helper.
+ * @returns {import("./index.js").MailerDeliveryPayload[]} - Delivered payloads.
+ */
+export function deliveries() {
+  return deliveriesStore.slice()
+}
+
+/**
+ * Runs the clearDeliveries helper.
+ * @returns {void} - No return value.
+ */
+export function clearDeliveries() {
+  deliveriesStore.length = 0
+}
+
+/**
+ * Runs the setDeliveryHandler helper.
+ * @param {(payload: import("./index.js").MailerDeliveryPayload) => Promise<?> | ?} handler - Delivery handler.
+ * @returns {void} - No return value.
+ */
+export function setDeliveryHandler(handler) {
+  deliveryHandler = handler
+}
+
+/**
+ * Runs the getDeliveryHandler helper.
+ * @returns {((payload: import("./index.js").MailerDeliveryPayload) => Promise<?> | ?) | null} - Handler or null.
+ */
+export function getDeliveryHandler() {
+  return deliveryHandler
+}
+
+/**
+ * Runs the deliverPayload helper.
+ * @param {import("./index.js").MailerDeliveryPayload} payload - Mail delivery payload.
+ * @returns {Promise<import("./index.js").MailerDeliveryPayload | ?>} - Handler result.
+ */
+export async function deliverPayload(payload) {
+  if (await isTestingEnvironment()) {
+    deliveriesStore.push(payload)
+    return payload
+  }
+
+  const configuration = await configurationResolver()
+  const backend = configuration.getMailerBackend()
+
+  if (backend?.deliver) {
+    return await backend.deliver({payload, configuration})
+  }
+
+  const handler = deliveryHandler
+
+  if (!handler) {
+    throw new Error(`No mail delivery handler configured for "${payload.subject}" to "${payload.to}"`)
+  }
+
+  return await handler(payload)
+}
+
+/**
+ * Runs the enqueuePayload helper.
+ * @param {import("./index.js").MailerDeliveryPayload} payload - Mail delivery payload.
+ * @returns {Promise<string | import("./index.js").MailerDeliveryPayload | null>} - Job id or payload in test mode.
+ */
+export async function enqueuePayload(payload) {
+  if (await isTestingEnvironment()) {
+    deliveriesStore.push(payload)
+    return payload
+  }
+
+  const {default: mailDeliveryJob} = await import("../jobs/mail-delivery.js")
+
+  return await mailDeliveryJob.performLater(payload)
+}

package/src/mailer/delivery.js

@@ -0,0 +1,70 @@
+// @ts-check
+
+/**
+ * Represents a prepared mail delivery.
+ */
+export default class MailerDelivery {
+  /**
+   * Narrows the runtime value to the documented type.
+    @type {import("./base.js").VelociousMailerBase} */
+  mailer
+  /**
+   * Narrows the runtime value to the documented type.
+    @type {Promise<?>} */
+  actionPromise
+  /**
+   * Narrows the runtime value to the documented type.
+    @type {string} */
+  actionName
+
+  /**
+   * Runs constructor.
+   * @param {object} args - Constructor args.
+   * @param {import("./base.js").VelociousMailerBase} args.mailer - Mailer instance.
+   * @param {Promise<?>} args.actionPromise - Action promise.
+   * @param {string} args.actionName - Action name.
+   */
+  constructor({mailer, actionPromise, actionName}) {
+    this.mailer = mailer
+    this.actionPromise = actionPromise
+    this.actionName = actionName
+  }
+
+  /**
+   * Runs build payload.
+   * @returns {Promise<import("./index.js").MailerDeliveryPayload>} - Rendered mailer payload.
+   */
+  async buildPayload() {
+    await this.actionPromise
+
+    return /** Narrows the runtime value to the documented type. @type {import("./index.js").MailerDeliveryPayload} */ (await this.mailer._buildPayload())
+  }
+
+  /**
+   * Runs deliver now.
+   * @returns {Promise<import("./index.js").MailerDeliveryPayload | ?>} - Delivered payload or handler result.
+   */
+  async deliverNow() {
+    const payload = await this.buildPayload()
+
+    return await this.mailer._deliverPayload(payload)
+  }
+
+  /**
+   * Runs deliver later.
+   * @returns {Promise<string | import("./index.js").MailerDeliveryPayload | null>} - Job id or payload in test mode.
+   */
+  async deliverLater() {
+    const payload = await this.buildPayload()
+
+    return await this.mailer._enqueuePayload(payload)
+  }
+
+  /**
+   * Runs deliver laver.
+   * @returns {Promise<string | import("./index.js").MailerDeliveryPayload | null>} - Job id or payload in test mode.
+   */
+  async deliverLaver() {
+    return await this.deliverLater()
+  }
+}

package/src/mailer/index.js

@@ -0,0 +1,24 @@
+// @ts-check
+
+/** @typedef {{to: ?, subject: string, from?: ?, cc?: ?, bcc?: ?, replyTo?: ?, headers?: Record<string, string>, html: string, mailer: string, action: string}} MailerDeliveryPayload */
+
+import {
+  clearDeliveries,
+  deliverPayload,
+  deliveries,
+  enqueuePayload,
+  getDeliveryHandler,
+  setDeliveryHandler,
+  VelociousMailerBase
+} from "./base.js"
+
+export {
+  VelociousMailerBase,
+  clearDeliveries,
+  deliverPayload,
+  deliveries,
+  enqueuePayload,
+  getDeliveryHandler,
+  setDeliveryHandler
+}
+export default VelociousMailerBase

package/src/mailer.js

@@ -0,0 +1,15 @@
+// @ts-check
+
+/** @typedef {{to: ?, subject: string, from?: ?, cc?: ?, bcc?: ?, replyTo?: ?, headers?: Record<string, string>, html: string, mailer: string, action: string}} MailerDeliveryPayload */
+
+export {
+  VelociousMailerBase,
+  clearDeliveries,
+  deliverPayload,
+  deliveries,
+  enqueuePayload,
+  getDeliveryHandler,
+  setDeliveryHandler
+} from "./mailer/index.js"
+export {default as SmtpMailerBackend} from "./mailer/backends/smtp.js"
+export {default} from "./mailer/index.js"

package/src/plugins/sqljs-wasm-route-controller.js

@@ -0,0 +1,70 @@
+import fs from "node:fs/promises"
+import path from "node:path"
+
+import Controller from "../controller.js"
+
+/**
+ * Runs valid asset file name.
+ * @param {?} assetFileName - Asset file name.
+ * @returns {boolean} - Whether asset file name is safe.
+ */
+function validAssetFileName(assetFileName) {
+  return typeof assetFileName === "string"
+    && assetFileName.length > 0
+    && !assetFileName.includes("/")
+    && !assetFileName.includes("\\")
+    && !assetFileName.includes("..")
+}
+
+/**
+ * Runs normalize sql js asset file name.
+ * @param {string} assetFileName - Requested sql.js asset file name.
+ * @returns {string} - Normalized sql.js asset file name.
+ */
+function normalizeSqlJsAssetFileName(assetFileName) {
+  if (assetFileName === "sql-wasm-browser.wasm") {
+    return "sql-wasm.wasm"
+  }
+
+  return assetFileName
+}
+
+/** Serves sql.js assets from the backend for sqlite-web locateFile callbacks. */
+export default class SqlJsWasmRouteController extends Controller {
+  /**
+   * Runs show.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async show() {
+    const {sqlJsAssetFileName, sqlJsDistDirectory} = this.params()
+
+    if (!validAssetFileName(sqlJsAssetFileName)) {
+      throw new Error(`Invalid sql.js asset file name: ${String(sqlJsAssetFileName)}`)
+    }
+
+    if (typeof sqlJsDistDirectory !== "string" || sqlJsDistDirectory.length < 1) {
+      throw new Error(`Expected sql.js dist directory path to be a string, got: ${String(sqlJsDistDirectory)}`)
+    }
+
+    const normalizedSqlJsAssetFileName = normalizeSqlJsAssetFileName(sqlJsAssetFileName)
+    const assetPath = path.join(sqlJsDistDirectory, normalizedSqlJsAssetFileName)
+
+    try {
+      await fs.access(assetPath)
+    } catch (error) {
+      const ensuredError = /**
+                            * Narrows the runtime value to the documented type.
+                             @type {{code?: string}} */ (error)
+
+      if (ensuredError.code === "ENOENT") {
+        await this.render({json: {errorMessage: "Not found", status: "error"}, status: "not-found"})
+        return
+      }
+
+      throw error
+    }
+
+    this.response().setHeader("Cache-Control", "public, max-age=3600")
+    this.sendFile(assetPath)
+  }
+}

package/src/plugins/sqljs-wasm-route.js

@@ -0,0 +1,71 @@
+import {createRequire} from "node:module"
+import path from "node:path"
+import SqlJsWasmRouteController from "./sqljs-wasm-route-controller.js"
+
+const require = createRequire(import.meta.url)
+const sqlJsEntryPath = require.resolve("sql.js")
+const sqlJsDistDirectory = path.dirname(sqlJsEntryPath)
+
+/**
+ * InstallSqlJsWasmRouteArgs type.
+ * @typedef {object} InstallSqlJsWasmRouteArgs
+ * @property {import("../configuration.js").default} configuration - Velocious configuration instance.
+ * @property {string} [routePrefix] - Route prefix used for sql.js asset serving.
+ */
+
+/**
+ * SqlJsLocateFileFromBackendArgs type.
+ * @typedef {object} SqlJsLocateFileFromBackendArgs
+ * @property {string} backendBaseUrl - Backend base URL (for example `https://api.example.com`).
+ * @property {string} [routePrefix] - Route prefix used for sql.js asset serving.
+ */
+
+/**
+ * Runs normalize route prefix.
+ * @param {string} routePrefix - Route prefix input.
+ * @returns {string} - Normalized route prefix.
+ */
+function normalizeRoutePrefix(routePrefix) {
+  if (!routePrefix.startsWith("/")) {
+    throw new Error(`Expected route prefix to start with '/', got: ${routePrefix}`)
+  }
+
+  if (routePrefix.length > 1 && routePrefix.endsWith("/")) {
+    return routePrefix.slice(0, -1)
+  }
+
+  return routePrefix
+}
+
+/**
+ * Installs a route-resolver hook that serves `sql.js/dist/*` files from the running Velocious backend.
+ * @param {InstallSqlJsWasmRouteArgs} args - Options object.
+ * @returns {void} - No return value.
+ */
+export default function installSqlJsWasmRoute(args) {
+  const {configuration, routePrefix = "/velocious/sqljs"} = args
+
+  if (!configuration) throw new Error("No configuration given")
+
+  const normalizedRoutePrefix = normalizeRoutePrefix(routePrefix)
+
+  configuration.routes((routes) => {
+    routes.get(`${normalizedRoutePrefix}/:sqlJsAssetFileName`, {
+      params: {sqlJsDistDirectory},
+      to: [SqlJsWasmRouteController, "show"]
+    })
+  })
+}
+
+/**
+ * Creates a sqlite-web `locateFile(file)` callback pointing to a Velocious backend route.
+ * @param {SqlJsLocateFileFromBackendArgs} args - Options object.
+ * @returns {(file: string) => string} - sql.js locateFile callback.
+ */
+export function sqlJsLocateFileFromBackend(args) {
+  const {backendBaseUrl, routePrefix = "/velocious/sqljs"} = args
+  const normalizedRoutePrefix = normalizeRoutePrefix(routePrefix)
+  const baseUrl = backendBaseUrl.replace(/\/+$/, "")
+
+  return (file) => `${baseUrl}${normalizedRoutePrefix}/${encodeURIComponent(file)}`
+}

package/src/record-payload-values.js

@@ -0,0 +1,83 @@
+// @ts-check
+
+/**
+ * @typedef {{_associationCounts?: Map<string, number>, _computedAbilities?: Map<string, boolean>, _queryDataValues?: Map<string, ?>}} RecordPayloadValuesTarget
+ */
+
+/**
+ * Read an association count attached to a record/frontend-model payload.
+ * @param {RecordPayloadValuesTarget} target - Record-like object holding association count payload values.
+ * @param {string} attributeName - Association count attribute name.
+ * @returns {number} Attached count value, or 0 when it was not loaded.
+ */
+export function readPayloadAssociationCount(target, attributeName) {
+  if (!target._associationCounts) return 0
+  if (!target._associationCounts.has(attributeName)) return 0
+
+  return /** @type {number} */ (target._associationCounts.get(attributeName))
+}
+
+/**
+ * Store an association count attached to a record/frontend-model payload.
+ * @param {RecordPayloadValuesTarget} target - Record-like object holding association count payload values.
+ * @param {string} attributeName - Association count attribute name.
+ * @param {number} value - Count value.
+ * @returns {void}
+ */
+export function setPayloadAssociationCount(target, attributeName, value) {
+  if (!target._associationCounts) target._associationCounts = new Map()
+
+  target._associationCounts.set(attributeName, value)
+}
+
+/**
+ * Read a computed ability attached to a record/frontend-model payload.
+ * @param {RecordPayloadValuesTarget} target - Record-like object holding ability payload values.
+ * @param {string} action - Ability action name.
+ * @returns {boolean} Attached ability value, or false when it was not loaded.
+ */
+export function readPayloadComputedAbility(target, action) {
+  if (!target._computedAbilities) return false
+  if (!target._computedAbilities.has(action)) return false
+
+  return Boolean(target._computedAbilities.get(action))
+}
+
+/**
+ * Store a computed ability attached to a record/frontend-model payload.
+ * @param {RecordPayloadValuesTarget} target - Record-like object holding ability payload values.
+ * @param {string} action - Ability action name.
+ * @param {boolean} value - Whether the current ability permits the action on this record.
+ * @returns {void}
+ */
+export function setPayloadComputedAbility(target, action, value) {
+  if (!target._computedAbilities) target._computedAbilities = new Map()
+
+  target._computedAbilities.set(action, Boolean(value))
+}
+
+/**
+ * Read a queryData value attached to a record/frontend-model payload.
+ * @param {RecordPayloadValuesTarget} target - Record-like object holding queryData payload values.
+ * @param {string} name - queryData alias name.
+ * @returns {?} Attached queryData value, or null when it was not loaded.
+ */
+export function readPayloadQueryData(target, name) {
+  if (!target._queryDataValues) return null
+  if (!target._queryDataValues.has(name)) return null
+
+  return target._queryDataValues.get(name)
+}
+
+/**
+ * Store a queryData value attached to a record/frontend-model payload.
+ * @param {RecordPayloadValuesTarget} target - Record-like object holding queryData payload values.
+ * @param {string} name - queryData alias name.
+ * @param {?} value - Attached queryData value.
+ * @returns {void}
+ */
+export function setPayloadQueryData(target, name, value) {
+  if (!target._queryDataValues) target._queryDataValues = new Map()
+
+  target._queryDataValues.set(name, value)
+}

package/src/routes/app-routes.js

@@ -0,0 +1,17 @@
+// @ts-check
+
+import {digg} from "diggerize"
+
+export default class VelociousRoutesAppRoutes {
+  /**
+   * Runs get routes.
+   * @param {import("../configuration.js").default} configuration - Configuration instance.
+   * @returns {Promise<import("./index.js").default>} - Resolves with the routes.
+   */
+  static async getRoutes(configuration) {
+    // Every client need to make their own routes because they probably can't be shared across different worker threads
+    const routesImport = await configuration.getEnvironmentHandler().importApplicationRoutes()
+
+    return digg(routesImport, "routes")
+  }
+}