velocious 1.0.431 → 1.0.433

package/build/database/record/attachments/normalize-input.js

@@ -0,0 +1,213 @@
+// @ts-check
+
+import UploadedFile from "../../../http-server/client/uploaded-file/uploaded-file.js"
+
+/**
+ * Runs base name.
+ * @param {string} value - Path-like value.
+ * @returns {string} - Basename-like filename.
+ */
+function baseName(value) {
+  const withoutTrailingSeparators = value.replace(/[\\/]+$/, "")
+
+  if (!withoutTrailingSeparators) return ""
+
+  const normalized = withoutTrailingSeparators.replaceAll("\\", "/")
+  const parts = normalized.split("/")
+
+  return parts[parts.length - 1] || ""
+}
+
+/**
+ * Runs is plain object.
+ * @param {?} value - Candidate value.
+ * @returns {value is Record<string, ?>} - Whether value is a plain object.
+ */
+function isPlainObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false
+
+  const prototype = Object.getPrototypeOf(value)
+
+  return prototype === Object.prototype || prototype === null
+}
+
+/**
+ * Runs is uint8 array.
+ * @param {?} value - Candidate value.
+ * @returns {value is Uint8Array} - Whether value is a byte array.
+ */
+function isUint8Array(value) {
+  return value instanceof Uint8Array
+}
+
+/**
+ * Runs is array buffer.
+ * @param {?} value - Candidate value.
+ * @returns {value is ArrayBuffer} - Whether value is array buffer.
+ */
+function isArrayBuffer(value) {
+  return value instanceof ArrayBuffer
+}
+
+/**
+ * Runs is array buffer like.
+ * @param {?} value - Candidate value.
+ * @returns {value is {arrayBuffer: () => Promise<ArrayBuffer>}} - Whether value supports arrayBuffer().
+ */
+function isArrayBufferLike(value) {
+  return Boolean(value && typeof value === "object" && typeof /**
+                                                               * Narrows the runtime value to the documented type.
+                                                                @type {?} */ (value).arrayBuffer === "function")
+}
+
+/**
+ * Runs to buffer.
+ * @param {Uint8Array | Buffer | ArrayBuffer | string} value - Value.
+ * @returns {Buffer} - Buffer value.
+ */
+function toBuffer(value) {
+  if (Buffer.isBuffer(value)) return value
+  if (typeof value === "string") return Buffer.from(value)
+  if (isArrayBuffer(value)) return Buffer.from(value)
+  if (isUint8Array(value)) return Buffer.from(value)
+
+  throw new Error("Unsupported attachment content type")
+}
+
+/**
+ * Runs uploaded file buffer.
+ * @param {UploadedFile} uploadedFile - Uploaded file.
+ * @param {import("../../../environment-handlers/base.js").default | undefined} environmentHandler - Environment handler.
+ * @returns {Promise<Buffer>} - File content buffer.
+ */
+async function uploadedFileBuffer(uploadedFile, environmentHandler) {
+  const memoryBuffer = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {{getBuffer?: () => Buffer}} */ (uploadedFile).getBuffer?.()
+
+  if (Buffer.isBuffer(memoryBuffer)) return memoryBuffer
+
+  const tempPath = /**
+                    * Narrows the runtime value to the documented type.
+                     @type {{getPath?: () => string}} */ (uploadedFile).getPath?.()
+
+  if (typeof tempPath === "string" && tempPath.length > 0) {
+    if (!environmentHandler || typeof environmentHandler.readAttachmentInputFile !== "function") {
+      throw new Error("Attachment temp-path input is unsupported in this environment")
+    }
+
+    return await environmentHandler.readAttachmentInputFile(tempPath)
+  }
+
+  throw new Error("Unsupported uploaded file type")
+}
+
+/**
+ * NormalizedAttachmentInput type.
+ * @typedef {object} NormalizedAttachmentInput
+ * @property {number} byteSize - File size in bytes.
+ * @property {Buffer} contentBuffer - Raw content bytes.
+ * @property {string} contentBase64 - Base64 encoded content.
+ * @property {string | null} contentType - Content type.
+ * @property {string} filename - Filename.
+ */
+
+/**
+ * Runs normalize record attachment input.
+ * @param {?} input - Attachment input.
+ * @param {object} [args] - Options.
+ * @param {boolean} [args.allowPathInput] - Whether `{path: ...}` input is allowed.
+ * @param {string[]} [args.allowedPathPrefixes] - Optional allowlist for path input.
+ * @param {string} [args.defaultFilename] - Optional default filename.
+ * @param {import("../../../environment-handlers/base.js").default} [args.environmentHandler] - Optional environment handler for Node-only file operations.
+ * @returns {Promise<NormalizedAttachmentInput>} - Normalized attachment input.
+ */
+export default async function normalizeRecordAttachmentInput(input, args = {}) {
+  const defaultFilename = args.defaultFilename || "attachment.bin"
+  const environmentHandler = args.environmentHandler
+  /**
+   * Defines buffer.
+    @type {Buffer} */
+  let buffer
+  /**
+   * Content type.
+    @type {string | null} */
+  let contentType = null
+  /**
+   * Defines filename.
+    @type {string | undefined} */
+  let filename
+
+  if (input instanceof UploadedFile) {
+    buffer = await uploadedFileBuffer(input, environmentHandler)
+    filename = input.filename()
+    contentType = input.contentType() || null
+  } else if (isPlainObject(input) && typeof input.path === "string" && input.path.length > 0) {
+    if (args.allowPathInput !== true) {
+      throw new Error("Attachment path input is disabled")
+    }
+
+    if (!environmentHandler || typeof environmentHandler.resolveAttachmentInputPath !== "function") {
+      throw new Error("Attachment path input is unsupported in this environment")
+    }
+
+    const allowedPathPrefixes = Array.isArray(args.allowedPathPrefixes)
+      ? args.allowedPathPrefixes.filter((entry) => typeof entry === "string" && entry.length > 0)
+      : []
+    const {buffer: fileBuffer, filePath} = await environmentHandler.resolveAttachmentInputPath({
+      allowedPathPrefixes,
+      inputPath: input.path
+    })
+
+    buffer = fileBuffer
+    filename = typeof input.filename === "string" && input.filename.length > 0 ? input.filename : baseName(filePath)
+    contentType = typeof input.contentType === "string" && input.contentType.length > 0 ? input.contentType : null
+  } else if (isPlainObject(input) && typeof input.contentBase64 === "string") {
+    buffer = Buffer.from(input.contentBase64, "base64")
+    filename = typeof input.filename === "string" && input.filename.length > 0 ? input.filename : defaultFilename
+    contentType = typeof input.contentType === "string" && input.contentType.length > 0 ? input.contentType : null
+  } else if (isPlainObject(input) && "content" in input) {
+    buffer = toBuffer(input.content)
+    filename = typeof input.filename === "string" && input.filename.length > 0 ? input.filename : defaultFilename
+    contentType = typeof input.contentType === "string" && input.contentType.length > 0 ? input.contentType : null
+  } else if (isArrayBufferLike(input)) {
+    const arrayBuffer = await input.arrayBuffer()
+
+    buffer = Buffer.from(arrayBuffer)
+    filename = typeof /**
+                       * Narrows the runtime value to the documented type.
+                        @type {?} */ (input).name === "string" && /**
+                                                                   * Narrows the runtime value to the documented type.
+                                                                    @type {?} */ (input).name.length > 0
+      ? /**
+         * Narrows the runtime value to the documented type.
+          @type {?} */ (input).name
+      : defaultFilename
+    contentType = typeof /**
+                          * Narrows the runtime value to the documented type.
+                           @type {?} */ (input).type === "string" && /**
+                                                                      * Narrows the runtime value to the documented type.
+                                                                       @type {?} */ (input).type.length > 0
+      ? /**
+         * Narrows the runtime value to the documented type.
+          @type {?} */ (input).type
+      : null
+  } else if (typeof input === "string" || Buffer.isBuffer(input) || isArrayBuffer(input) || isUint8Array(input)) {
+    buffer = toBuffer(input)
+    filename = defaultFilename
+  } else {
+    throw new Error("Unsupported attachment input")
+  }
+
+  const normalizedFilename = typeof filename === "string" && filename.length > 0
+    ? baseName(filename)
+    : ""
+
+  return {
+    byteSize: buffer.length,
+    contentBuffer: buffer,
+    contentBase64: buffer.toString("base64"),
+    contentType,
+    filename: normalizedFilename || defaultFilename
+  }
+}

package/build/database/record/attachments/storage-drivers/filesystem.js

@@ -0,0 +1,114 @@
+// @ts-check
+
+import fs from "fs/promises"
+import path from "path"
+
+/**
+ * Runs normalize base url.
+ * @param {string} value - URL value.
+ * @returns {string} - URL without trailing slash.
+ */
+function normalizeBaseUrl(value) {
+  return value.replace(/\/+$/, "")
+}
+
+/**
+ * Runs encode storage key.
+ * @param {string} storageKey - Storage key.
+ * @returns {string} - URL-safe storage key.
+ */
+function encodeStorageKey(storageKey) {
+  return storageKey.split("/").map((entry) => encodeURIComponent(entry)).join("/")
+}
+
+/**
+ * Filesystem attachment storage driver.
+ */
+export default class FilesystemAttachmentStorageDriver {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options.
+   * @param {import("../../../../configuration.js").default} args.configuration - Configuration instance.
+   * @param {Record<string, ?>} [args.options] - Driver options.
+   */
+  constructor({configuration, options = {}}) {
+    this.configuration = configuration
+    this.options = options
+  }
+
+  /**
+   * Runs directory.
+   * @returns {string} - Root directory for attachment files.
+   */
+  directory() {
+    if (typeof this.options.directory === "string" && this.options.directory.length > 0) {
+      return path.resolve(this.options.directory)
+    }
+
+    return path.resolve(this.configuration.getDirectory(), "tmp/attachments/filesystem")
+  }
+
+  /**
+   * Runs write.
+   * @param {object} args - Options.
+   * @param {string} args.attachmentId - Attachment id.
+   * @param {{contentBuffer: Buffer, filename: string}} args.input - Normalized attachment input.
+   * @returns {Promise<{storageKey: string}>} - Storage key result.
+   */
+  async write({attachmentId, input}) {
+    const normalizedFilename = path.basename(input.filename || "attachment.bin")
+    const storageKey = `${attachmentId}-${normalizedFilename}`
+    const filePath = path.resolve(this.directory(), storageKey)
+
+    await fs.mkdir(path.dirname(filePath), {recursive: true})
+    await fs.writeFile(filePath, input.contentBuffer)
+
+    return {storageKey}
+  }
+
+  /**
+   * Runs read.
+   * @param {object} args - Options.
+   * @param {string} args.storageKey - Storage key.
+   * @returns {Promise<Buffer>} - Attachment bytes.
+   */
+  async read({storageKey}) {
+    const filePath = path.resolve(this.directory(), storageKey)
+
+    return await fs.readFile(filePath)
+  }
+
+  /**
+   * Runs delete.
+   * @param {object} args - Options.
+   * @param {string} args.storageKey - Storage key.
+   * @returns {Promise<void>} - Resolves when file has been deleted.
+   */
+  async delete({storageKey}) {
+    const filePath = path.resolve(this.directory(), storageKey)
+
+    try {
+      await fs.unlink(filePath)
+    } catch (error) {
+      if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") {
+        throw error
+      }
+    }
+  }
+
+  /**
+   * Runs url.
+   * @param {object} args - Options.
+   * @param {string} args.storageKey - Storage key.
+   * @returns {Promise<string>} - Resolvable URL.
+   */
+  async url({storageKey}) {
+    if (typeof this.options.baseUrl === "string" && this.options.baseUrl.length > 0) {
+      return `${normalizeBaseUrl(this.options.baseUrl)}/${encodeStorageKey(storageKey)}`
+    }
+
+    const filePath = path.resolve(this.directory(), storageKey)
+
+    return `file://${filePath}`
+  }
+}

package/build/database/record/attachments/storage-drivers/native.js

@@ -0,0 +1,146 @@
+// @ts-check
+
+/**
+ * Runs throw missing method.
+ * @param {object} args - Args.
+ * @param {string} args.driverName - Driver name.
+ * @param {string} args.methodName - Method name.
+ * @returns {never} - Always throws.
+ */
+function throwMissingMethod({driverName, methodName}) {
+  throw new Error(`Attachment storage driver "${driverName}" requires a "${methodName}" callback`)
+}
+
+/**
+ * Runs to buffer.
+ * @param {?} value - Candidate value.
+ * @returns {Buffer} - Buffer value.
+ */
+function toBuffer(value) {
+  if (Buffer.isBuffer(value)) return value
+  if (value instanceof Uint8Array) return Buffer.from(value)
+  if (value instanceof ArrayBuffer) return Buffer.from(value)
+  if (typeof value === "string") return Buffer.from(value, "base64")
+
+  throw new Error(`Unsupported native attachment read result: ${String(value)}`)
+}
+
+/**
+ * Native attachment storage driver.
+ * This driver delegates all I/O to user-provided callbacks.
+ */
+export default class NativeAttachmentStorageDriver {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options.
+   * @param {import("../../../../configuration.js").default} [args.configuration] - Configuration instance.
+   * @param {string} args.name - Driver name.
+   * @param {Record<string, ?>} [args.options] - Driver options.
+   */
+  constructor({configuration, name, options = {}}) {
+    this.configuration = configuration
+    this.name = name
+    this.options = options
+  }
+
+  /**
+   * Runs write.
+   * @param {object} args - Write args.
+   * @param {string} args.attachmentId - Attachment id.
+   * @param {{contentBase64: string, contentType: string | null, filename: string}} args.input - Normalized attachment input.
+   * @param {import("../../index.js").default} args.model - Model instance.
+   * @param {string} args.name - Attachment name.
+   * @returns {Promise<{storageKey: string}>} - Storage key result.
+   */
+  async write({attachmentId, input, model, name}) {
+    if (typeof this.options.write !== "function") {
+      throwMissingMethod({driverName: this.name, methodName: "write"})
+    }
+
+    const result = await this.options.write({
+      attachmentId,
+      attachmentName: name,
+      contentBase64: input.contentBase64,
+      contentType: input.contentType,
+      filename: input.filename,
+      model
+    })
+
+    if (!result || typeof result.storageKey !== "string" || result.storageKey.length < 1) {
+      throw new Error(`Attachment storage driver "${this.name}" write callback must return {storageKey}`)
+    }
+
+    return {storageKey: result.storageKey}
+  }
+
+  /**
+   * Runs read.
+   * @param {object} args - Read args.
+   * @param {string} args.storageKey - Storage key.
+   * @param {import("../../index.js").default} args.model - Model instance.
+   * @param {string} args.name - Attachment name.
+   * @param {Record<string, ?>} args.row - Attachment row.
+   * @returns {Promise<Buffer>} - Attachment bytes.
+   */
+  async read({model, name, row, storageKey}) {
+    if (typeof this.options.read !== "function") {
+      throwMissingMethod({driverName: this.name, methodName: "read"})
+    }
+
+    const result = await this.options.read({
+      attachmentId: row.id || "",
+      attachmentName: name,
+      model,
+      row,
+      storageKey
+    })
+
+    return toBuffer(result)
+  }
+
+  /**
+   * Runs delete.
+   * @param {object} args - Delete args.
+   * @param {string} args.storageKey - Storage key.
+   * @param {import("../../index.js").default} args.model - Model instance.
+   * @param {string} args.name - Attachment name.
+   * @param {Record<string, ?>} args.row - Attachment row.
+   * @returns {Promise<void>} - Resolves when deleted.
+   */
+  async delete({model, name, row, storageKey}) {
+    if (typeof this.options.delete !== "function") return
+
+    await this.options.delete({
+      attachmentId: row.id || "",
+      attachmentName: name,
+      model,
+      row,
+      storageKey
+    })
+  }
+
+  /**
+   * Runs url.
+   * @param {object} args - URL args.
+   * @param {string} args.storageKey - Storage key.
+   * @param {import("../../index.js").default} args.model - Model instance.
+   * @param {string} args.name - Attachment name.
+   * @param {Record<string, ?>} args.row - Attachment row.
+   * @returns {Promise<string | null>} - Attachment URL.
+   */
+  async url({model, name, row, storageKey}) {
+    if (typeof this.options.url !== "function") return null
+
+    const value = await this.options.url({
+      attachmentId: row.id || "",
+      attachmentName: name,
+      model,
+      row,
+      storageKey
+    })
+
+    if (typeof value === "string" && value.length > 0) return value
+
+    return null
+  }
+}