@backblaze-labs/b2-sdk 0.2.0 → 0.4.0

package/dist/simulator/validation.js.map

@@ -1 +1 @@
-{"version":3,"file":"validation.js","names":[],"sources":["../../src/simulator/validation.ts"],"sourcesContent":["/**\n * B2 spec-compliance validation helpers for the simulator.\n *\n * Each function mirrors a documented B2 input limit (file name length,\n * bucket name regex, file-info byte budget, etc.). Validators return\n * `null` for valid input or a `{ code, message }` pair that the handler\n * converts into a synthetic `400`/`403` response with the right B2\n * error code.\n *\n * Keeping validation in one module makes the simulator's \"what does B2\n * reject?\" surface auditable in a single file. Doc references inline at\n * each rule so the spec source is immediate.\n *\n * @packageDocumentation\n */\n\nimport {\n  BUCKET_NAME_MAX,\n  BUCKET_NAME_MIN,\n  BUCKET_NAME_RESERVED_PREFIX,\n  FILE_NAME_MAX_BYTES,\n  getB2FileNameByteLength,\n  hasB2FileNameControlCharacter,\n  hasValidB2BucketNameShape,\n  isB2BucketNameIpv4Address,\n} from '../internal/b2-naming.ts'\nimport { utf8Encoder } from '../util/text-codec.ts'\n\n/** Shape returned by validation functions when input is rejected. */\nexport interface ValidationError {\n  readonly code: string\n  readonly message: string\n}\n\n// ---------------------------------------------------------------------------\n// Bucket name (`b2_create_bucket`, `b2_update_bucket`)\n// ---------------------------------------------------------------------------\n\nexport { BUCKET_NAME_MAX, BUCKET_NAME_MIN }\n\n/**\n * Validates a bucket name against B2's documented rules.\n *\n * @param name - Caller-supplied bucket name.\n *\n * @returns A `{ code, message }` pair on failure, or `null` when valid.\n *\n * @see https://www.backblaze.com/apidocs/b2-create-bucket\n */\nexport function validateBucketName(name: string): ValidationError | null {\n  if (typeof name !== 'string' || name.length < BUCKET_NAME_MIN || name.length > BUCKET_NAME_MAX) {\n    return {\n      code: 'invalid_bucket_name',\n      message: `bucketName must be ${BUCKET_NAME_MIN}-${BUCKET_NAME_MAX} characters`,\n    }\n  }\n  if (isB2BucketNameIpv4Address(name)) {\n    return {\n      code: 'invalid_bucket_name',\n      message: 'bucketName must not be formatted as an IPv4 address',\n    }\n  }\n  if (!hasValidB2BucketNameShape(name)) {\n    return {\n      code: 'invalid_bucket_name',\n      message:\n        'bucketName must contain only letters, digits, hyphens, and periods; cannot start or end with punctuation or contain consecutive periods',\n    }\n  }\n  if (name.startsWith(BUCKET_NAME_RESERVED_PREFIX)) {\n    return {\n      code: 'invalid_bucket_name',\n      message: `bucketName cannot start with the reserved prefix \"${BUCKET_NAME_RESERVED_PREFIX}\"`,\n    }\n  }\n  return null\n}\n\n// ---------------------------------------------------------------------------\n// File name (every upload / hide / copy entry point)\n// ---------------------------------------------------------------------------\n\nexport { FILE_NAME_MAX_BYTES }\n\n/**\n * Validates a file name against B2's documented rules. Mirrors the\n * server-side checks B2 runs on `b2_upload_file` / `b2_hide_file` /\n * `b2_start_large_file` / `b2_copy_file` filename inputs.\n *\n * @param name - Caller-supplied file name (raw, unencoded).\n *\n * @returns A `{ code, message }` pair on failure, or `null` when valid.\n *\n * @see https://www.backblaze.com/apidocs/b2-upload-file\n */\nexport function validateFileName(name: string): ValidationError | null {\n  if (typeof name !== 'string' || name.length === 0) {\n    return { code: 'invalid_file_name', message: 'fileName must be a non-empty string' }\n  }\n  const byteLength = getB2FileNameByteLength(name)\n  if (byteLength === null) {\n    return {\n      code: 'invalid_file_name',\n      message: 'fileName exceeds the 1024-byte UTF-8 limit',\n    }\n  }\n  if (hasB2FileNameControlCharacter(name)) {\n    return {\n      code: 'invalid_file_name',\n      message: 'fileName must not contain control characters (U+0000-U+001F or U+007F)',\n    }\n  }\n  // Path segments equal to `.` or `..` alone are illegal per B2 docs.\n  // Embedded `..` within a segment (e.g. `a..b`) is fine, and a path\n  // like `../foo` is fine because the SDK doesn't interpret it; only\n  // bare `.` or `..` as a complete name is rejected.\n  if (name === '.' || name === '..') {\n    return {\n      code: 'invalid_file_name',\n      message: 'fileName cannot be exactly \".\" or \"..\"',\n    }\n  }\n  // No leading or trailing slash, no `//`.\n  if (name.startsWith('/') || name.endsWith('/') || name.includes('//')) {\n    return {\n      code: 'invalid_file_name',\n      message: 'fileName cannot start with \"/\", end with \"/\", or contain \"//\"',\n    }\n  }\n  return null\n}\n\n// ---------------------------------------------------------------------------\n// File-info / Bucket-info byte budget\n// ---------------------------------------------------------------------------\n\n/** Per-file fileInfo total size cap (sum of key+value bytes). */\nexport const FILE_INFO_TOTAL_MAX = 2048\n/** Per-key fileInfo value byte cap. */\nexport const FILE_INFO_VALUE_MAX = 2048\n/** Allowed key character set (case-insensitive). */\nconst FILE_INFO_KEY_REGEX = /^[a-zA-Z0-9_-]+$/\n\n/**\n * Validates a `fileInfo` record against B2's byte-budget and\n * key-shape rules.\n *\n * @param info - Caller-supplied fileInfo record.\n *\n * @returns A `{ code, message }` pair on failure, or `null` when valid.\n *\n * @see https://www.backblaze.com/apidocs/b2-upload-file\n */\nexport function validateFileInfo(info: Record<string, string>): ValidationError | null {\n  let total = 0\n  for (const [key, value] of Object.entries(info)) {\n    if (!FILE_INFO_KEY_REGEX.test(key)) {\n      return {\n        code: 'invalid_file_info',\n        message: `fileInfo key \"${key}\" must match ^[a-zA-Z0-9_-]+$`,\n      }\n    }\n    if (typeof value !== 'string') {\n      return { code: 'invalid_file_info', message: `fileInfo value for \"${key}\" must be a string` }\n    }\n    const keyBytes = utf8Encoder.encode(key).byteLength\n    const valueBytes = utf8Encoder.encode(value).byteLength\n    if (valueBytes > FILE_INFO_VALUE_MAX) {\n      return {\n        code: 'invalid_file_info',\n        message: `fileInfo value for \"${key}\" exceeds ${FILE_INFO_VALUE_MAX} bytes`,\n      }\n    }\n    total += keyBytes + valueBytes\n  }\n  if (total > FILE_INFO_TOTAL_MAX) {\n    return {\n      code: 'invalid_file_info',\n      message: `fileInfo total size ${total} bytes exceeds the ${FILE_INFO_TOTAL_MAX}-byte limit`,\n    }\n  }\n  return null\n}\n\n/** Per-bucket bucketInfo total max keys. */\nexport const BUCKET_INFO_MAX_KEYS = 10\n/** Per-key bucketInfo value byte cap. */\nexport const BUCKET_INFO_VALUE_MAX = 2048\n/** Allowed key character set for bucketInfo. */\nconst BUCKET_INFO_KEY_REGEX = /^[a-zA-Z0-9_-]+$/\n\n/**\n * Validates a `bucketInfo` record against B2's per-bucket metadata rules.\n *\n * @param info - Caller-supplied bucketInfo record.\n *\n * @returns A `{ code, message }` pair on failure, or `null` when valid.\n *\n * @see https://www.backblaze.com/apidocs/b2-create-bucket\n */\nexport function validateBucketInfo(info: Record<string, string>): ValidationError | null {\n  const entries = Object.entries(info)\n  if (entries.length > BUCKET_INFO_MAX_KEYS) {\n    return {\n      code: 'invalid_bucket_info',\n      message: `bucketInfo cannot have more than ${BUCKET_INFO_MAX_KEYS} keys (got ${entries.length})`,\n    }\n  }\n  for (const [key, value] of entries) {\n    if (!BUCKET_INFO_KEY_REGEX.test(key)) {\n      return {\n        code: 'invalid_bucket_info',\n        message: `bucketInfo key \"${key}\" must match ^[a-zA-Z0-9_-]+$`,\n      }\n    }\n    if (typeof value !== 'string') {\n      return {\n        code: 'invalid_bucket_info',\n        message: `bucketInfo value for \"${key}\" must be a string`,\n      }\n    }\n    const valueBytes = utf8Encoder.encode(value).byteLength\n    if (valueBytes > BUCKET_INFO_VALUE_MAX) {\n      return {\n        code: 'invalid_bucket_info',\n        message: `bucketInfo value for \"${key}\" exceeds ${BUCKET_INFO_VALUE_MAX} bytes`,\n      }\n    }\n  }\n  return null\n}\n\n// ---------------------------------------------------------------------------\n// maxFileCount caps per endpoint\n// ---------------------------------------------------------------------------\n\n/**\n * Per-endpoint upper bound on the `maxFileCount` (or `maxKeyCount` /\n * `maxPartCount`) request field. Sourced from the B2 endpoint docs.\n */\nexport const LIST_ENDPOINT_CAPS = {\n  /** `b2_list_file_names.maxFileCount` cap. */\n  b2_list_file_names: 10_000,\n  /** `b2_list_file_versions.maxFileCount` cap. */\n  b2_list_file_versions: 10_000,\n  /** `b2_list_unfinished_large_files.maxFileCount` cap. */\n  b2_list_unfinished_large_files: 100,\n  /** `b2_list_keys.maxKeyCount` cap. */\n  b2_list_keys: 10_000,\n  /** `b2_list_parts.maxPartCount` cap. */\n  b2_list_parts: 10_000,\n} as const\n\n/**\n * Validates a `maxFileCount` (or `maxKeyCount` / `maxPartCount`) value\n * against the per-endpoint cap documented by B2.\n *\n * @param requested - Caller-supplied count.\n * @param endpoint - Which list endpoint this applies to.\n *\n * @returns A `{ code, message }` pair on failure, or `null` when valid.\n */\nexport function validateMaxCount(\n  requested: number | undefined,\n  endpoint: keyof typeof LIST_ENDPOINT_CAPS,\n): ValidationError | null {\n  if (requested === undefined) return null\n  if (!Number.isInteger(requested) || requested < 1) {\n    return {\n      code: 'bad_request',\n      message: `maxFileCount must be a positive integer (got ${requested})`,\n    }\n  }\n  const cap = LIST_ENDPOINT_CAPS[endpoint]\n  if (requested > cap) {\n    return {\n      code: 'bad_request',\n      message: `maxFileCount ${requested} exceeds the ${endpoint} cap of ${cap}`,\n    }\n  }\n  return null\n}\n"],"mappings":"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"}
+{"version":3,"file":"validation.js","names":[],"sources":["../../src/simulator/validation.ts"],"sourcesContent":["/**\n * B2 spec-compliance validation helpers for the simulator.\n *\n * Each function mirrors a documented B2 input limit (file name length,\n * bucket name regex, file-info byte budget, etc.). Validators return\n * `null` for valid input or a `{ code, message }` pair that the handler\n * converts into a synthetic `400`/`403` response with the right B2\n * error code.\n *\n * Keeping validation in one module makes the simulator's \"what does B2\n * reject?\" surface auditable in a single file. Doc references inline at\n * each rule so the spec source is immediate.\n *\n * @packageDocumentation\n */\n\nimport {\n  assertValidBucketInfo as assertValidClientBucketInfo,\n  assertValidCorsRules as assertValidClientCorsRules,\n} from '../bucket-validation.ts'\nimport { B2BucketConfigurationError } from '../errors/index.ts'\nimport {\n  BUCKET_NAME_MAX,\n  BUCKET_NAME_MIN,\n  BUCKET_NAME_RESERVED_PREFIX,\n  FILE_NAME_MAX_BYTES,\n  getB2FileNameByteLength,\n  hasB2FileNameControlCharacter,\n  hasValidB2BucketNameShape,\n  isB2BucketNameIpv4Address,\n} from '../internal/b2-naming.ts'\nimport { Capability } from '../types/auth.ts'\nimport {\n  BUCKET_INFO_VALUES_MAX_BYTES,\n  BucketRetentionMode,\n  BucketType,\n  CORS_MAX_AGE_SECONDS_MAX,\n  CorsOperation,\n  type CorsRule,\n} from '../types/bucket.ts'\nimport { EventType } from '../types/notifications.ts'\nimport { utf8Encoder } from '../util/text-codec.ts'\n\nexport {\n  BUCKET_INFO_KEY_MAX_BYTES,\n  BUCKET_INFO_KEY_MIN_BYTES,\n  BUCKET_INFO_KEY_PATTERN,\n  BUCKET_INFO_RESERVED_PREFIX,\n  BUCKET_INFO_VALUES_MAX_BYTES,\n  CORS_MAX_AGE_SECONDS_MAX,\n  CORS_RULE_MAX_BYTES,\n  CORS_RULE_NAME_MAX_LENGTH,\n  CORS_RULE_NAME_MIN_LENGTH,\n  CORS_RULE_NAME_PATTERN,\n  CORS_RULE_NAME_RESERVED_PREFIX,\n  CORS_RULES_MAX_COUNT,\n} from '../types/bucket.ts'\n\n/**\n * Deprecated compatibility alias for the former simulator bucketInfo pair-count cap.\n *\n * @deprecated B2 bucketInfo has no documented pair-count cap. Use the byte\n * limit constants instead.\n */\nexport const BUCKET_INFO_MAX_KEYS = Number.POSITIVE_INFINITY\n\n/**\n * Deprecated compatibility alias for the former simulator per-value bucketInfo cap.\n *\n * @deprecated B2 bucketInfo limits aggregate value bytes, not per-value bytes.\n * Use {@link BUCKET_INFO_VALUES_MAX_BYTES}.\n */\nexport const BUCKET_INFO_VALUE_MAX = BUCKET_INFO_VALUES_MAX_BYTES\n\n/** Shape returned by validation functions when input is rejected. */\nexport interface ValidationError {\n  readonly code: string\n  readonly message: string\n}\n\n// ---------------------------------------------------------------------------\n// Application keys (`b2_create_key`)\n// ---------------------------------------------------------------------------\n\n/** Minimum length for application key names. */\nexport const KEY_NAME_MIN = 1\n/** Maximum length for application key names. */\nexport const KEY_NAME_MAX = 100\n\nconst VALID_CAPABILITIES = new Set<string>(Object.values(Capability))\n\n/**\n * Validates application-key capabilities against B2's supported capability set.\n *\n * @param capabilities - Caller-supplied capabilities array.\n *\n * @returns A `{ code, message }` pair on failure, or `null` when valid.\n *\n * @see https://www.backblaze.com/apidocs/b2-create-key\n */\nexport function validateCreateKeyCapabilities(capabilities: unknown): ValidationError | null {\n  if (!Array.isArray(capabilities)) {\n    return { code: 'bad_request', message: 'capabilities must be an array' }\n  }\n  if (capabilities.length === 0) {\n    return { code: 'bad_request', message: 'capabilities must not be empty' }\n  }\n  const unknownCapabilities = capabilities.filter(\n    (capability) => typeof capability !== 'string' || !VALID_CAPABILITIES.has(capability),\n  )\n  if (unknownCapabilities.length > 0) {\n    return {\n      code: 'bad_request',\n      message: `unknown capabilities: ${unknownCapabilities.map(String).join(', ')}`,\n    }\n  }\n  return null\n}\n\n/**\n * Returns a frozen copy of a previously validated application-key capability list.\n *\n * @param capabilities - Validated caller-supplied capabilities.\n *\n * @returns An immutable capability list safe to store internally.\n */\nexport function normalizeCreateKeyCapabilities(\n  capabilities: readonly Capability[],\n): readonly Capability[] {\n  return Object.freeze([...capabilities])\n}\n\n/**\n * Validates application-key names against B2's documented length limits.\n *\n * @param keyName - Caller-supplied keyName.\n *\n * @returns A `{ code, message }` pair on failure, or `null` when valid.\n *\n * @see https://www.backblaze.com/apidocs/b2-create-key\n */\nexport function validateCreateKeyName(keyName: unknown): ValidationError | null {\n  if (typeof keyName !== 'string') {\n    return { code: 'bad_request', message: 'keyName must be a string' }\n  }\n  if (keyName.length < KEY_NAME_MIN || keyName.length > KEY_NAME_MAX) {\n    return {\n      code: 'bad_request',\n      message: `keyName must be ${KEY_NAME_MIN}-${KEY_NAME_MAX} characters`,\n    }\n  }\n  return null\n}\n\n// ---------------------------------------------------------------------------\n// Bucket name (`b2_create_bucket`, `b2_update_bucket`)\n// ---------------------------------------------------------------------------\n\nexport { BUCKET_NAME_MAX, BUCKET_NAME_MIN }\n\n/**\n * Validates a bucket name against B2's documented rules.\n *\n * @param name - Caller-supplied bucket name.\n *\n * @returns A `{ code, message }` pair on failure, or `null` when valid.\n *\n * @see https://www.backblaze.com/apidocs/b2-create-bucket\n */\nexport function validateBucketName(name: string): ValidationError | null {\n  if (typeof name !== 'string' || name.length < BUCKET_NAME_MIN || name.length > BUCKET_NAME_MAX) {\n    return {\n      code: 'invalid_bucket_name',\n      message: `bucketName must be ${BUCKET_NAME_MIN}-${BUCKET_NAME_MAX} characters`,\n    }\n  }\n  if (isB2BucketNameIpv4Address(name)) {\n    return {\n      code: 'invalid_bucket_name',\n      message: 'bucketName must not be formatted as an IPv4 address',\n    }\n  }\n  if (!hasValidB2BucketNameShape(name)) {\n    return {\n      code: 'invalid_bucket_name',\n      message:\n        'bucketName must contain only letters, digits, hyphens, and periods; cannot start or end with punctuation or contain consecutive periods',\n    }\n  }\n  if (name.startsWith(BUCKET_NAME_RESERVED_PREFIX)) {\n    return {\n      code: 'invalid_bucket_name',\n      message: `bucketName cannot start with the reserved prefix \"${BUCKET_NAME_RESERVED_PREFIX}\"`,\n    }\n  }\n  return null\n}\n\n// ---------------------------------------------------------------------------\n// File name (every upload / hide / copy entry point)\n// ---------------------------------------------------------------------------\n\nexport { FILE_NAME_MAX_BYTES }\n\n/**\n * Validates a file name against B2's documented rules. Mirrors the\n * server-side checks B2 runs on `b2_upload_file` / `b2_hide_file` /\n * `b2_start_large_file` / `b2_copy_file` filename inputs.\n *\n * @param name - Caller-supplied file name (raw, unencoded).\n *\n * @returns A `{ code, message }` pair on failure, or `null` when valid.\n *\n * @see https://www.backblaze.com/apidocs/b2-upload-file\n */\nexport function validateFileName(name: string): ValidationError | null {\n  if (typeof name !== 'string' || name.length === 0) {\n    return { code: 'invalid_file_name', message: 'fileName must be a non-empty string' }\n  }\n  const byteLength = getB2FileNameByteLength(name)\n  if (byteLength === null) {\n    return {\n      code: 'invalid_file_name',\n      message: 'fileName exceeds the 1024-byte UTF-8 limit',\n    }\n  }\n  if (hasB2FileNameControlCharacter(name)) {\n    return {\n      code: 'invalid_file_name',\n      message: 'fileName must not contain control characters (U+0000-U+001F or U+007F)',\n    }\n  }\n  // Path segments equal to `.` or `..` alone are illegal per B2 docs.\n  // Embedded `..` within a segment (e.g. `a..b`) is fine, and a path\n  // like `../foo` is fine because the SDK doesn't interpret it; only\n  // bare `.` or `..` as a complete name is rejected.\n  if (name === '.' || name === '..') {\n    return {\n      code: 'invalid_file_name',\n      message: 'fileName cannot be exactly \".\" or \"..\"',\n    }\n  }\n  // No leading or trailing slash, no `//`.\n  if (name.startsWith('/') || name.endsWith('/') || name.includes('//')) {\n    return {\n      code: 'invalid_file_name',\n      message: 'fileName cannot start with \"/\", end with \"/\", or contain \"//\"',\n    }\n  }\n  return null\n}\n\n// ---------------------------------------------------------------------------\n// File-info / Bucket-info byte budget\n// ---------------------------------------------------------------------------\n\n/** Per-file fileInfo total size cap (sum of key+value bytes). */\nexport const FILE_INFO_TOTAL_MAX = 2048\n/** Per-key fileInfo value byte cap. */\nexport const FILE_INFO_VALUE_MAX = 2048\n/** Allowed key character set (case-insensitive). */\nconst FILE_INFO_KEY_REGEX = /^[a-zA-Z0-9_-]+$/\n\n/**\n * Validates a `fileInfo` record against B2's byte-budget and\n * key-shape rules.\n *\n * @param info - Caller-supplied fileInfo record.\n *\n * @returns A `{ code, message }` pair on failure, or `null` when valid.\n *\n * @see https://www.backblaze.com/apidocs/b2-upload-file\n */\nexport function validateFileInfo(info: Record<string, string>): ValidationError | null {\n  let total = 0\n  for (const [key, value] of Object.entries(info)) {\n    if (!FILE_INFO_KEY_REGEX.test(key)) {\n      return {\n        code: 'invalid_file_info',\n        message: `fileInfo key \"${key}\" must match ^[a-zA-Z0-9_-]+$`,\n      }\n    }\n    if (typeof value !== 'string') {\n      return { code: 'invalid_file_info', message: `fileInfo value for \"${key}\" must be a string` }\n    }\n    const keyBytes = utf8Encoder.encode(key).byteLength\n    const valueBytes = utf8Encoder.encode(value).byteLength\n    if (valueBytes > FILE_INFO_VALUE_MAX) {\n      return {\n        code: 'invalid_file_info',\n        message: `fileInfo value for \"${key}\" exceeds ${FILE_INFO_VALUE_MAX} bytes`,\n      }\n    }\n    total += keyBytes + valueBytes\n  }\n  if (total > FILE_INFO_TOTAL_MAX) {\n    return {\n      code: 'invalid_file_info',\n      message: `fileInfo total size ${total} bytes exceeds the ${FILE_INFO_TOTAL_MAX}-byte limit`,\n    }\n  }\n  return null\n}\n\n/**\n * Validates a `bucketInfo` record against B2's per-bucket metadata rules.\n *\n * @param info - Caller-supplied bucketInfo record.\n *\n * @returns A `{ code, message }` pair on failure, or `null` when valid.\n *\n * @see https://www.backblaze.com/docs/cloud-storage-buckets\n */\nexport function validateBucketInfo(info: unknown): ValidationError | null {\n  try {\n    assertValidClientBucketInfo(info as Record<string, string>)\n  } catch (err) {\n    return bucketConfigurationValidationError(err)\n  }\n  return null\n}\n\n// ---------------------------------------------------------------------------\n// maxFileCount caps per endpoint\n// ---------------------------------------------------------------------------\n\n/**\n * Per-endpoint upper bound on the `maxFileCount` (or `maxKeyCount` /\n * `maxPartCount`) request field. Sourced from the B2 endpoint docs.\n */\nexport const LIST_ENDPOINT_CAPS = {\n  /** `b2_list_file_names.maxFileCount` cap. */\n  b2_list_file_names: 10_000,\n  /** `b2_list_file_versions.maxFileCount` cap. */\n  b2_list_file_versions: 10_000,\n  /** `b2_list_unfinished_large_files.maxFileCount` cap. */\n  b2_list_unfinished_large_files: 100,\n  /** `b2_list_keys.maxKeyCount` cap. */\n  b2_list_keys: 10_000,\n  /** `b2_list_parts.maxPartCount` cap. */\n  b2_list_parts: 10_000,\n} as const\n\n/**\n * Validates a `maxFileCount` (or `maxKeyCount` / `maxPartCount`) value\n * against the per-endpoint cap documented by B2.\n *\n * @param requested - Caller-supplied count.\n * @param endpoint - Which list endpoint this applies to.\n *\n * @returns A `{ code, message }` pair on failure, or `null` when valid.\n */\nexport function validateMaxCount(\n  requested: number | undefined,\n  endpoint: keyof typeof LIST_ENDPOINT_CAPS,\n): ValidationError | null {\n  if (requested === undefined) return null\n  if (!Number.isInteger(requested) || requested < 1) {\n    return {\n      code: 'bad_request',\n      message: `maxFileCount must be a positive integer (got ${requested})`,\n    }\n  }\n  const cap = LIST_ENDPOINT_CAPS[endpoint]\n  if (requested > cap) {\n    return {\n      code: 'bad_request',\n      message: `maxFileCount ${requested} exceeds the ${endpoint} cap of ${cap}`,\n    }\n  }\n  return null\n}\n\n// ---------------------------------------------------------------------------\n// Download authorization duration\n// ---------------------------------------------------------------------------\n\n/** Minimum `b2_get_download_authorization.validDurationInSeconds`. */\nexport const DOWNLOAD_AUTH_DURATION_MIN_SECONDS = 1\n/** Maximum `b2_get_download_authorization.validDurationInSeconds`. */\nexport const DOWNLOAD_AUTH_DURATION_MAX_SECONDS = 604_800\n\n/**\n * Validates a `b2_get_download_authorization` duration against B2's\n * documented inclusive 1-second to 7-day range.\n *\n * @param requested - Caller-supplied duration in seconds.\n *\n * @returns A `{ code, message }` pair on failure, or `null` when valid.\n */\nexport function validateDownloadAuthorizationDuration(requested: unknown): ValidationError | null {\n  if (\n    typeof requested !== 'number' ||\n    !Number.isInteger(requested) ||\n    requested < DOWNLOAD_AUTH_DURATION_MIN_SECONDS ||\n    requested > DOWNLOAD_AUTH_DURATION_MAX_SECONDS\n  ) {\n    return {\n      code: 'bad_request',\n      message: `validDurationInSeconds must be an integer from ${DOWNLOAD_AUTH_DURATION_MIN_SECONDS} through ${DOWNLOAD_AUTH_DURATION_MAX_SECONDS}`,\n    }\n  }\n  return null\n}\n\n/**\n * Validates a `b2_get_download_authorization` file name prefix.\n *\n * B2 allows an empty prefix, but the field must still be present as a\n * string so later prefix checks cannot crash on malformed request bodies.\n *\n * @param requested - Caller-supplied file name prefix.\n *\n * @returns A `{ code, message }` pair on failure, or `null` when valid.\n */\nexport function validateDownloadAuthorizationPrefix(requested: unknown): ValidationError | null {\n  if (typeof requested !== 'string') {\n    return { code: 'bad_request', message: 'fileNamePrefix must be a string' }\n  }\n  return null\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value)\n}\n\nfunction validateKnownFields(\n  value: Record<string, unknown>,\n  allowedFields: ReadonlySet<string>,\n  path: string,\n): ValidationError | null {\n  for (const field of Object.keys(value)) {\n    if (!allowedFields.has(field)) {\n      return {\n        code: 'bad_request',\n        message: `${path}.${field} is not a supported field`,\n      }\n    }\n  }\n  return null\n}\n\nfunction validateStringArray(\n  value: unknown,\n  path: string,\n  options: { readonly allowNull?: boolean; readonly requireNonEmpty?: boolean } = {},\n): ValidationError | null {\n  if (value === undefined && options.allowNull === true) return null\n  if (value === null && options.allowNull === true) return null\n  if (!Array.isArray(value)) {\n    return { code: 'bad_request', message: `${path} must be an array of strings` }\n  }\n  if (options.requireNonEmpty === true && value.length === 0) {\n    return { code: 'bad_request', message: `${path} must be a non-empty array` }\n  }\n  for (const [index, item] of value.entries()) {\n    if (typeof item !== 'string') {\n      return { code: 'bad_request', message: `${path}[${index}] must be a string` }\n    }\n  }\n  return null\n}\n\nfunction validateNonEmptyString(value: unknown, path: string): ValidationError | null {\n  if (typeof value !== 'string' || value.length === 0) {\n    return { code: 'bad_request', message: `${path} must be a non-empty string` }\n  }\n  return null\n}\n\nfunction validateNonNegativeInteger(value: unknown, path: string): ValidationError | null {\n  if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {\n    return { code: 'bad_request', message: `${path} must be a non-negative integer` }\n  }\n  return null\n}\n\nfunction validateIntegerAtMost(value: number, max: number, path: string): ValidationError | null {\n  if (value > max) {\n    return { code: 'bad_request', message: `${path} must not exceed ${max}` }\n  }\n  return null\n}\n\nfunction validatePositiveInteger(value: unknown, path: string): ValidationError | null {\n  if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {\n    return { code: 'bad_request', message: `${path} must be a positive integer` }\n  }\n  return null\n}\n\nfunction validateNullablePositiveInteger(value: unknown, path: string): ValidationError | null {\n  if (value === undefined || value === null) return null\n  return validatePositiveInteger(value, path)\n}\n\nfunction validateUniqueName(\n  names: Set<string>,\n  name: string,\n  path: string,\n): ValidationError | null {\n  if (names.has(name)) {\n    return { code: 'bad_request', message: `${path} must be unique` }\n  }\n  names.add(name)\n  return null\n}\n\n// ---------------------------------------------------------------------------\n// Bucket configuration (`b2_create_bucket`, `b2_update_bucket`)\n// ---------------------------------------------------------------------------\n\nconst REQUEST_BUCKET_TYPES = new Set<string>(Object.values(BucketType))\n\n/**\n * Validates a create/update request `bucketType`.\n *\n * @param bucketType - Caller-supplied bucket type.\n *\n * @returns A `{ code, message }` pair on failure, or `null` when valid.\n *\n * @see https://www.backblaze.com/apidocs/b2-create-bucket\n * @see https://www.backblaze.com/apidocs/b2-update-bucket\n */\nexport function validateBucketType(bucketType: unknown): ValidationError | null {\n  if (typeof bucketType !== 'string' || !REQUEST_BUCKET_TYPES.has(bucketType)) {\n    return { code: 'bad_request', message: 'bucketType must be a known request bucket type' }\n  }\n  return null\n}\n\n/**\n * Validates a `b2_list_buckets.bucketTypes` filter.\n *\n * @param bucketTypes - Caller-supplied bucket type filter.\n *\n * @returns A `{ code, message }` pair on failure, or `null` when valid.\n *\n * @see https://www.backblaze.com/apidocs/b2-list-buckets\n */\nexport function validateBucketTypes(bucketTypes: unknown): ValidationError | null {\n  if (bucketTypes === undefined) return null\n  if (!Array.isArray(bucketTypes)) {\n    return { code: 'bad_request', message: 'bucketTypes must be an array' }\n  }\n  if (bucketTypes.length === 0) {\n    return { code: 'bad_request', message: 'bucketTypes must not be empty' }\n  }\n  if (bucketTypes.length === 1 && bucketTypes[0] === 'all') return null\n  if (bucketTypes.includes('all')) {\n    return { code: 'bad_request', message: \"bucketTypes may contain 'all' only by itself\" }\n  }\n  for (const [index, bucketType] of bucketTypes.entries()) {\n    if (typeof bucketType !== 'string') {\n      return {\n        code: 'bad_request',\n        message: `bucketTypes[${index}] must be a string`,\n      }\n    }\n  }\n  return null\n}\n\nconst CORS_RULE_FIELDS = new Set([\n  'allowedHeaders',\n  'allowedOperations',\n  'allowedOrigins',\n  'corsRuleName',\n  'exposeHeaders',\n  'maxAgeSeconds',\n])\n\nconst KNOWN_CORS_OPERATIONS = new Set<string>(Object.values(CorsOperation))\n\n/**\n * Validates B2 CORS rule structure for bucket create/update requests.\n *\n * @param rules - Caller-supplied CORS rules.\n *\n * @returns A `{ code, message }` pair on failure, or `null` when valid.\n *\n * @see https://www.backblaze.com/docs/cloud-storage-cross-origin-resource-sharing-rules\n */\nexport function validateCorsRules(rules: unknown): ValidationError | null {\n  try {\n    assertValidClientCorsRules(rules as readonly CorsRule[])\n  } catch (err) {\n    return bucketConfigurationValidationError(err)\n  }\n\n  if (!Array.isArray(rules)) {\n    return { code: 'bad_request', message: 'corsRules must be an array' }\n  }\n\n  const names = new Set<string>()\n  for (const [index, rule] of rules.entries()) {\n    const rulePath = `corsRules[${index}]`\n    if (!isRecord(rule)) {\n      return { code: 'bad_request', message: `${rulePath} must be an object` }\n    }\n\n    const fieldError = validateKnownFields(rule, CORS_RULE_FIELDS, rulePath)\n    if (fieldError) return fieldError\n\n    const nameError = validateNonEmptyString(rule['corsRuleName'], `${rulePath}.corsRuleName`)\n    if (nameError) return nameError\n    const ruleName = rule['corsRuleName'] as string\n    const uniqueNameError = validateUniqueName(names, ruleName, `${rulePath}.corsRuleName`)\n    if (uniqueNameError) return uniqueNameError\n\n    const originsError = validateStringArray(rule['allowedOrigins'], `${rulePath}.allowedOrigins`, {\n      requireNonEmpty: true,\n    })\n    if (originsError) return originsError\n\n    const operationsError = validateStringArray(\n      rule['allowedOperations'],\n      `${rulePath}.allowedOperations`,\n      { requireNonEmpty: true },\n    )\n    if (operationsError) return operationsError\n    for (const operation of rule['allowedOperations'] as readonly string[]) {\n      if (!KNOWN_CORS_OPERATIONS.has(operation)) {\n        return {\n          code: 'bad_request',\n          message: `${rulePath}.allowedOperations contains an unknown operation`,\n        }\n      }\n    }\n\n    const headersError = validateStringArray(rule['allowedHeaders'], `${rulePath}.allowedHeaders`, {\n      allowNull: true,\n    })\n    if (headersError) return headersError\n\n    const exposeError = validateStringArray(rule['exposeHeaders'], `${rulePath}.exposeHeaders`, {\n      allowNull: true,\n    })\n    if (exposeError) return exposeError\n\n    const ageError = validateNonNegativeInteger(rule['maxAgeSeconds'], `${rulePath}.maxAgeSeconds`)\n    if (ageError) return ageError\n    const maxAgeError = validateIntegerAtMost(\n      rule['maxAgeSeconds'] as number,\n      CORS_MAX_AGE_SECONDS_MAX,\n      `${rulePath}.maxAgeSeconds`,\n    )\n    if (maxAgeError) return maxAgeError\n  }\n\n  return null\n}\n\nfunction bucketConfigurationValidationError(err: unknown): ValidationError {\n  if (err instanceof B2BucketConfigurationError) {\n    return { code: err.code, message: err.message }\n  }\n  throw err\n}\n\nconst LIFECYCLE_RULE_FIELDS = new Set([\n  'daysFromHidingToDeleting',\n  'daysFromStartingToCancelingUnfinishedLargeFiles',\n  'daysFromUploadingToHiding',\n  'fileNamePrefix',\n])\n\n/**\n * Validates B2 lifecycle rule structure for bucket create/update requests.\n *\n * @param rules - Caller-supplied lifecycle rules.\n *\n * @returns A `{ code, message }` pair on failure, or `null` when valid.\n *\n * @see https://www.backblaze.com/docs/cloud-storage-lifecycle-rules\n */\nexport function validateLifecycleRules(rules: unknown): ValidationError | null {\n  if (!Array.isArray(rules)) {\n    return { code: 'bad_request', message: 'lifecycleRules must be an array' }\n  }\n\n  for (const [index, rule] of rules.entries()) {\n    const rulePath = `lifecycleRules[${index}]`\n    if (!isRecord(rule)) {\n      return { code: 'bad_request', message: `${rulePath} must be an object` }\n    }\n\n    const fieldError = validateKnownFields(rule, LIFECYCLE_RULE_FIELDS, rulePath)\n    if (fieldError) return fieldError\n\n    const deletingError = validateNullablePositiveInteger(\n      rule['daysFromHidingToDeleting'],\n      `${rulePath}.daysFromHidingToDeleting`,\n    )\n    if (deletingError) return deletingError\n\n    const hidingError = validateNullablePositiveInteger(\n      rule['daysFromUploadingToHiding'],\n      `${rulePath}.daysFromUploadingToHiding`,\n    )\n    if (hidingError) return hidingError\n\n    const cancelError = validateNullablePositiveInteger(\n      rule['daysFromStartingToCancelingUnfinishedLargeFiles'],\n      `${rulePath}.daysFromStartingToCancelingUnfinishedLargeFiles`,\n    )\n    if (cancelError) return cancelError\n\n    if (\n      rule['daysFromHidingToDeleting'] == null &&\n      rule['daysFromUploadingToHiding'] == null &&\n      rule['daysFromStartingToCancelingUnfinishedLargeFiles'] == null\n    ) {\n      return {\n        code: 'bad_request',\n        message: `${rulePath} must set at least one lifecycle action`,\n      }\n    }\n\n    if (typeof rule['fileNamePrefix'] !== 'string') {\n      return { code: 'bad_request', message: `${rulePath}.fileNamePrefix must be a string` }\n    }\n  }\n\n  return null\n}\n\nconst DEFAULT_RETENTION_FIELDS = new Set(['mode', 'period'])\nconst RETENTION_PERIOD_FIELDS = new Set(['duration', 'unit'])\nconst DEFAULT_RETENTION_MODES = new Set<string>(Object.values(BucketRetentionMode))\nconst OBJECT_LOCK_RETENTION_MAX_DAYS = 3000\n\n/**\n * Validates default Object Lock retention policy structure for bucket requests.\n *\n * @param policy - Caller-supplied default retention policy.\n *\n * @returns A `{ code, message }` pair on failure, or `null` when valid.\n *\n * @see https://www.backblaze.com/docs/cloud-storage-object-lock\n */\nexport function validateDefaultRetention(policy: unknown): ValidationError | null {\n  if (!isRecord(policy)) {\n    return { code: 'bad_request', message: 'defaultRetention must be an object' }\n  }\n\n  const fieldError = validateKnownFields(policy, DEFAULT_RETENTION_FIELDS, 'defaultRetention')\n  if (fieldError) return fieldError\n\n  const mode = policy['mode']\n  if (typeof mode !== 'string' || !DEFAULT_RETENTION_MODES.has(mode)) {\n    return {\n      code: 'bad_request',\n      message: 'defaultRetention.mode must be \"compliance\", \"governance\", or \"none\"',\n    }\n  }\n\n  const period = policy['period']\n  if (mode === BucketRetentionMode.None) {\n    if (period !== null) {\n      return {\n        code: 'bad_request',\n        message: 'defaultRetention.period must be null when mode is \"none\"',\n      }\n    }\n    return null\n  }\n\n  if (!isRecord(period)) {\n    return {\n      code: 'bad_request',\n      message: 'defaultRetention.period must be an object for retention modes',\n    }\n  }\n\n  const periodFieldError = validateKnownFields(\n    period,\n    RETENTION_PERIOD_FIELDS,\n    'defaultRetention.period',\n  )\n  if (periodFieldError) return periodFieldError\n\n  const durationError = validatePositiveInteger(\n    period['duration'],\n    'defaultRetention.period.duration',\n  )\n  if (durationError) return durationError\n  if (!Number.isSafeInteger(period['duration'])) {\n    return {\n      code: 'bad_request',\n      message: 'defaultRetention.period.duration must be a safe integer',\n    }\n  }\n\n  if (period['unit'] !== 'days' && period['unit'] !== 'years') {\n    return {\n      code: 'bad_request',\n      message: 'defaultRetention.period.unit must be \"days\" or \"years\"',\n    }\n  }\n  const durationDays =\n    period['unit'] === 'days'\n      ? (period['duration'] as number)\n      : (period['duration'] as number) * 365\n  if (!Number.isFinite(durationDays) || durationDays > OBJECT_LOCK_RETENTION_MAX_DAYS) {\n    return {\n      code: 'bad_request',\n      message: `defaultRetention.period must not exceed ${OBJECT_LOCK_RETENTION_MAX_DAYS} days`,\n    }\n  }\n\n  return null\n}\n\nconst REPLICATION_CONFIG_FIELDS = new Set(['asReplicationSource', 'asReplicationDestination'])\nconst REPLICATION_SOURCE_FIELDS = new Set(['replicationRules', 'sourceApplicationKeyId'])\nconst REPLICATION_DESTINATION_FIELDS = new Set(['sourceToDestinationKeyMapping'])\nconst REPLICATION_RULE_FIELDS = new Set([\n  'destinationBucketId',\n  'fileNamePrefix',\n  'includeExistingFiles',\n  'isEnabled',\n  'priority',\n  'replicationRuleName',\n])\n\nfunction validateReplicationRule(rule: unknown, rulePath: string): ValidationError | null {\n  if (!isRecord(rule)) {\n    return { code: 'bad_request', message: `${rulePath} must be an object` }\n  }\n\n  const fieldError = validateKnownFields(rule, REPLICATION_RULE_FIELDS, rulePath)\n  if (fieldError) return fieldError\n\n  const destinationError = validateNonEmptyString(\n    rule['destinationBucketId'],\n    `${rulePath}.destinationBucketId`,\n  )\n  if (destinationError) return destinationError\n\n  if (typeof rule['fileNamePrefix'] !== 'string') {\n    return { code: 'bad_request', message: `${rulePath}.fileNamePrefix must be a string` }\n  }\n\n  if (typeof rule['includeExistingFiles'] !== 'boolean') {\n    return { code: 'bad_request', message: `${rulePath}.includeExistingFiles must be a boolean` }\n  }\n\n  if (typeof rule['isEnabled'] !== 'boolean') {\n    return { code: 'bad_request', message: `${rulePath}.isEnabled must be a boolean` }\n  }\n\n  const priorityError = validatePositiveInteger(rule['priority'], `${rulePath}.priority`)\n  if (priorityError) return priorityError\n\n  const nameError = validateNonEmptyString(\n    rule['replicationRuleName'],\n    `${rulePath}.replicationRuleName`,\n  )\n  if (nameError) return nameError\n\n  return null\n}\n\nfunction validateReplicationSource(source: unknown): ValidationError | null {\n  if (!isRecord(source)) {\n    return {\n      code: 'bad_request',\n      message: 'replicationConfiguration.asReplicationSource must be an object',\n    }\n  }\n\n  const fieldError = validateKnownFields(\n    source,\n    REPLICATION_SOURCE_FIELDS,\n    'replicationConfiguration.asReplicationSource',\n  )\n  if (fieldError) return fieldError\n\n  const sourceKeyError = validateNonEmptyString(\n    source['sourceApplicationKeyId'],\n    'replicationConfiguration.asReplicationSource.sourceApplicationKeyId',\n  )\n  if (sourceKeyError) return sourceKeyError\n\n  const rules = source['replicationRules']\n  if (!Array.isArray(rules)) {\n    return {\n      code: 'bad_request',\n      message: 'replicationConfiguration.asReplicationSource.replicationRules must be an array',\n    }\n  }\n\n  const names = new Set<string>()\n  for (const [index, rule] of rules.entries()) {\n    const rulePath = `replicationConfiguration.asReplicationSource.replicationRules[${index}]`\n    const ruleError = validateReplicationRule(rule, rulePath)\n    if (ruleError) return ruleError\n    const ruleName = (rule as Record<string, unknown>)['replicationRuleName'] as string\n    const uniqueNameError = validateUniqueName(names, ruleName, `${rulePath}.replicationRuleName`)\n    if (uniqueNameError) return uniqueNameError\n  }\n\n  return null\n}\n\nfunction validateReplicationDestination(destination: unknown): ValidationError | null {\n  if (!isRecord(destination)) {\n    return {\n      code: 'bad_request',\n      message: 'replicationConfiguration.asReplicationDestination must be an object',\n    }\n  }\n\n  const fieldError = validateKnownFields(\n    destination,\n    REPLICATION_DESTINATION_FIELDS,\n    'replicationConfiguration.asReplicationDestination',\n  )\n  if (fieldError) return fieldError\n\n  const mapping = destination['sourceToDestinationKeyMapping']\n  if (!isRecord(mapping)) {\n    return {\n      code: 'bad_request',\n      message:\n        'replicationConfiguration.asReplicationDestination.sourceToDestinationKeyMapping must be an object',\n    }\n  }\n\n  for (const [sourceKey, destinationKey] of Object.entries(mapping)) {\n    if (sourceKey.length === 0) {\n      return {\n        code: 'bad_request',\n        message:\n          'replicationConfiguration.asReplicationDestination.sourceToDestinationKeyMapping keys must be non-empty',\n      }\n    }\n    if (typeof destinationKey !== 'string' || destinationKey.length === 0) {\n      return {\n        code: 'bad_request',\n        message:\n          'replicationConfiguration.asReplicationDestination.sourceToDestinationKeyMapping values must be non-empty strings',\n      }\n    }\n  }\n\n  return null\n}\n\n/**\n * Validates B2 replication configuration structure for bucket requests.\n *\n * @param config - Caller-supplied replication configuration.\n *\n * @returns A `{ code, message }` pair on failure, or `null` when valid.\n *\n * @see https://www.backblaze.com/apidocs/b2-update-bucket\n */\nexport function validateReplicationConfiguration(config: unknown): ValidationError | null {\n  if (!isRecord(config)) {\n    return { code: 'bad_request', message: 'replicationConfiguration must be an object' }\n  }\n\n  const fieldError = validateKnownFields(\n    config,\n    REPLICATION_CONFIG_FIELDS,\n    'replicationConfiguration',\n  )\n  if (fieldError) return fieldError\n\n  if (!('asReplicationSource' in config) && !('asReplicationDestination' in config)) {\n    return {\n      code: 'bad_request',\n      message:\n        'replicationConfiguration must include asReplicationSource or asReplicationDestination',\n    }\n  }\n\n  const source = config['asReplicationSource']\n  if (source !== undefined && source !== null) {\n    const sourceError = validateReplicationSource(source)\n    if (sourceError) return sourceError\n  }\n\n  const destination = config['asReplicationDestination']\n  if (destination !== undefined && destination !== null) {\n    const destinationError = validateReplicationDestination(destination)\n    if (destinationError) return destinationError\n  }\n\n  return null\n}\n\n// ---------------------------------------------------------------------------\n// Event notification rules (`b2_set_bucket_notification_rules`)\n// ---------------------------------------------------------------------------\n\nconst NOTIFICATION_RULE_FIELDS = new Set([\n  'eventTypes',\n  'isEnabled',\n  'isSuspended',\n  'maxEventsPerBatch',\n  'name',\n  'objectNamePrefix',\n  'suspensionReason',\n  'targetConfiguration',\n])\n\nconst NOTIFICATION_TARGET_FIELDS = new Set([\n  'customHeaders',\n  'hmacSha256SigningSecret',\n  'targetType',\n  'url',\n])\n\nconst NOTIFICATION_CUSTOM_HEADER_FIELDS = new Set(['name', 'value'])\nconst NOTIFICATION_CUSTOM_HEADER_MAX_COUNT = 10\nconst NOTIFICATION_CUSTOM_HEADER_MAX_ENCODED_BYTES = 2048\nconst NOTIFICATION_CUSTOM_HEADER_RESERVED_PREFIX = 'x-bz-'\nconst HTTP_HEADER_NAME_RE = /^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$/\n\nconst KNOWN_NOTIFICATION_EVENT_TYPES = new Set<string>(Object.values(EventType))\n\nfunction encodedHeaderBytes(name: string, value: string): number | null {\n  try {\n    // B2 counts the URL-encoded name/value plus the `:\\r\\n` separator per header.\n    return encodeURIComponent(name).length + encodeURIComponent(value).length + 3\n  } catch {\n    return null\n  }\n}\n\nfunction isValidHeaderValue(value: string): boolean {\n  for (let i = 0; i < value.length; i++) {\n    const code = value.charCodeAt(i)\n    if (code === 9) continue\n    if (code < 32 || code === 127) return false\n  }\n  return true\n}\n\nfunction validateNotificationCustomHeaders(value: unknown, path: string): ValidationError | null {\n  if (value === undefined) return null\n  if (!Array.isArray(value)) {\n    return { code: 'bad_request', message: `${path} must be an array of objects` }\n  }\n  if (value.length > NOTIFICATION_CUSTOM_HEADER_MAX_COUNT) {\n    return {\n      code: 'bad_request',\n      message: `${path} must contain no more than ${NOTIFICATION_CUSTOM_HEADER_MAX_COUNT} entries`,\n    }\n  }\n\n  const names = new Set<string>()\n  let encodedBytes = 0\n  for (const [index, header] of value.entries()) {\n    const headerPath = `${path}[${index}]`\n    if (!isRecord(header)) {\n      return { code: 'bad_request', message: `${headerPath} must be an object` }\n    }\n    const fieldError = validateKnownFields(header, NOTIFICATION_CUSTOM_HEADER_FIELDS, headerPath)\n    if (fieldError) return fieldError\n    if (typeof header['name'] !== 'string' || header['name'].length === 0) {\n      return { code: 'bad_request', message: `${headerPath}.name must be a non-empty string` }\n    }\n    if (typeof header['value'] !== 'string') {\n      return { code: 'bad_request', message: `${headerPath}.value must be a string` }\n    }\n\n    const name = header['name']\n    const normalizedName = name.toLowerCase()\n    if (!HTTP_HEADER_NAME_RE.test(name)) {\n      return { code: 'bad_request', message: `${headerPath}.name must be a valid HTTP header name` }\n    }\n    if (normalizedName.startsWith(NOTIFICATION_CUSTOM_HEADER_RESERVED_PREFIX)) {\n      return {\n        code: 'bad_request',\n        message: `${headerPath}.name must not begin with X-Bz-`,\n      }\n    }\n    if (names.has(normalizedName)) {\n      return { code: 'bad_request', message: `${headerPath}.name must be unique` }\n    }\n    names.add(normalizedName)\n\n    const headerValue = header['value']\n    if (!isValidHeaderValue(headerValue)) {\n      return {\n        code: 'bad_request',\n        message: `${headerPath}.value must be a valid HTTP header value`,\n      }\n    }\n\n    const size = encodedHeaderBytes(name, headerValue)\n    if (size === null) {\n      return { code: 'bad_request', message: `${headerPath} must be URL-encodable` }\n    }\n    encodedBytes += size\n    if (encodedBytes > NOTIFICATION_CUSTOM_HEADER_MAX_ENCODED_BYTES) {\n      return {\n        code: 'bad_request',\n        message: `${path} URL-encoded name/value bytes must not exceed ${NOTIFICATION_CUSTOM_HEADER_MAX_ENCODED_BYTES}`,\n      }\n    }\n  }\n  return null\n}\n\n/**\n * Validates event notification rules for `b2_set_bucket_notification_rules`.\n *\n * @param rules - Caller-supplied event notification rules.\n *\n * @returns A `{ code, message }` pair on failure, or `null` when valid.\n *\n * @see https://www.backblaze.com/apidocs/b2-set-bucket-notification-rules\n */\nexport function validateNotificationRules(rules: unknown): ValidationError | null {\n  if (!Array.isArray(rules)) {\n    return {\n      code: 'bad_request',\n      message: 'eventNotificationRules must be an array',\n    }\n  }\n\n  const names = new Set<string>()\n  for (const [index, ruleValue] of rules.entries()) {\n    const rulePath = `eventNotificationRules[${index}]`\n    if (!isRecord(ruleValue)) {\n      return { code: 'bad_request', message: `${rulePath} must be an object` }\n    }\n\n    const fieldError = validateKnownFields(ruleValue, NOTIFICATION_RULE_FIELDS, rulePath)\n    if (fieldError) return fieldError\n\n    if (typeof ruleValue['isEnabled'] !== 'boolean') {\n      return {\n        code: 'bad_request',\n        message: `${rulePath}.isEnabled must be a boolean`,\n      }\n    }\n\n    const maxEventsPerBatch = ruleValue['maxEventsPerBatch']\n    if (\n      maxEventsPerBatch !== undefined &&\n      (typeof maxEventsPerBatch !== 'number' ||\n        !Number.isInteger(maxEventsPerBatch) ||\n        maxEventsPerBatch < 1)\n    ) {\n      return {\n        code: 'bad_request',\n        message: `${rulePath}.maxEventsPerBatch must be a positive integer`,\n      }\n    }\n\n    const name = ruleValue['name']\n    if (typeof name !== 'string' || name.length === 0) {\n      return {\n        code: 'bad_request',\n        message: `${rulePath}.name must be a non-empty string`,\n      }\n    }\n    if (names.has(name)) {\n      return {\n        code: 'bad_request',\n        message: `${rulePath}.name must be unique within eventNotificationRules`,\n      }\n    }\n    names.add(name)\n\n    const eventTypes = ruleValue['eventTypes']\n    if (!Array.isArray(eventTypes) || eventTypes.length === 0) {\n      return {\n        code: 'bad_request',\n        message: `${rulePath}.eventTypes must be a non-empty array`,\n      }\n    }\n    for (const eventType of eventTypes) {\n      if (typeof eventType !== 'string' || !KNOWN_NOTIFICATION_EVENT_TYPES.has(eventType)) {\n        return {\n          code: 'bad_request',\n          message: `${rulePath}.eventTypes contains an unknown event type`,\n        }\n      }\n    }\n\n    const targetConfiguration = ruleValue['targetConfiguration']\n    if (!isRecord(targetConfiguration)) {\n      return {\n        code: 'bad_request',\n        message: `${rulePath}.targetConfiguration must be an object`,\n      }\n    }\n\n    const targetFieldError = validateKnownFields(\n      targetConfiguration,\n      NOTIFICATION_TARGET_FIELDS,\n      `${rulePath}.targetConfiguration`,\n    )\n    if (targetFieldError) return targetFieldError\n\n    if (targetConfiguration['targetType'] !== 'webhook') {\n      return {\n        code: 'bad_request',\n        message: `${rulePath}.targetConfiguration.targetType must be \"webhook\"`,\n      }\n    }\n\n    const url = targetConfiguration['url']\n    if (typeof url !== 'string') {\n      return {\n        code: 'bad_request',\n        message: `${rulePath}.targetConfiguration.url must be a valid https URL`,\n      }\n    }\n    try {\n      if (new URL(url).protocol !== 'https:') {\n        return {\n          code: 'bad_request',\n          message: `${rulePath}.targetConfiguration.url must be a valid https URL`,\n        }\n      }\n    } catch {\n      return {\n        code: 'bad_request',\n        message: `${rulePath}.targetConfiguration.url must be a valid https URL`,\n      }\n    }\n\n    const customHeadersError = validateNotificationCustomHeaders(\n      targetConfiguration['customHeaders'],\n      `${rulePath}.targetConfiguration.customHeaders`,\n    )\n    if (customHeadersError) return customHeadersError\n  }\n\n  return null\n}\n"],"mappings":"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"}

package/dist/streams/file-source.cjs

@@ -1,11 +1,11 @@
 //#region src/streams/file-source.ts
-var FILE_STREAM_CHUNK_SIZE = 16 * 1024 * 1024;
+var FILE_STREAM_CHUNK_SIZE = 16777216;
 var FILE_SOURCE_INTERNAL = Symbol("FileSource.internal");
 /** @internal */
 var fileSourceTestHooks = {};
 function getNodeFsSync() {
 	const fs = globalThis.process?.getBuiltinModule?.("node:fs");
-	if (!isNodeFsSync(fs)) throw new Error("FileSource constructor requires Node.js 22.3+ synchronous filesystem APIs; use FileSource.fromPath() when synchronous filesystem access is unavailable.");
+	if (!isNodeFsSync(fs)) throw new Error("FileSource constructor requires process.getBuiltinModule(\"node:fs\") with synchronous filesystem APIs; use FileSource.fromPath() when synchronous filesystem access is unavailable.");
 	return fs;
 }
 function isNodeFsSync(value) {

package/dist/streams/file-source.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"file-source.cjs","names":[],"sources":["../../src/streams/file-source.ts"],"sourcesContent":["import type { ContentSource } from './source.ts'\n\nconst FILE_STREAM_CHUNK_SIZE = 16 * 1024 * 1024\n\n/** Filesystem path accepted by {@link FileSource}. */\nexport type FileSourcePath = string | URL\n\ninterface FileStatsLike {\n  readonly dev: number\n  readonly ino: number\n  readonly mode: number\n  readonly size: number\n  readonly mtimeMs: number\n  readonly ctimeMs: number\n  isFile(): boolean\n}\n\ninterface FileHandleLike {\n  read(\n    buffer: Uint8Array,\n    offset: number,\n    length: number,\n    position: number,\n  ): Promise<{ bytesRead: number }>\n  stat(): Promise<FileStatsLike>\n  close(): Promise<void>\n}\n\ninterface NodeFsSync {\n  lstatSync(path: FileSourcePath): FileStatsLike\n}\n\ninterface FileIdentity {\n  readonly dev: number\n  readonly ino: number\n  readonly size: number\n  readonly mtimeMs: number\n  readonly ctimeMs: number\n}\n\ninterface ToArrayBufferOptions {\n  readonly signal?: AbortSignal\n}\n\nconst FILE_SOURCE_INTERNAL = Symbol('FileSource.internal')\n\ninterface FileSourceInternalOptions {\n  readonly key: typeof FILE_SOURCE_INTERNAL\n  readonly identity: FileIdentity\n}\n\n/** @internal */\nexport const fileSourceTestHooks: {\n  afterReadIteration?: (filled: number) => Promise<void> | void\n  maxReadSize?: number\n  openFile?: (path: FileSourcePath, flags: number) => Promise<FileHandleLike>\n  platform?: string\n} = {}\n\nfunction getNodeFsSync(): NodeFsSync {\n  // FileSource exposes `size` synchronously, so the constructor cannot use the\n  // repo's usual `await import('node:...')` pattern for Node-only APIs. Keep the\n  // synchronous lookup here; async callers should prefer `FileSource.fromPath()`.\n  const processLike = (\n    globalThis as {\n      process?: { getBuiltinModule?: (id: string) => unknown }\n    }\n  ).process\n  const fs = processLike?.getBuiltinModule?.('node:fs')\n  if (!isNodeFsSync(fs)) {\n    throw new Error(\n      'FileSource constructor requires Node.js 22.3+ synchronous filesystem APIs; use FileSource.fromPath() when synchronous filesystem access is unavailable.',\n    )\n  }\n  return fs\n}\n\nfunction isNodeFsSync(value: unknown): value is NodeFsSync {\n  if (typeof value !== 'object' || value === null) return false\n  const candidate = value as Record<string, unknown>\n  return typeof candidate['lstatSync'] === 'function'\n}\n\nasync function fileOpenFlags(): Promise<number> {\n  const { constants } = await import('node:fs')\n  // O_NOFOLLOW and O_NONBLOCK are unavailable on some platforms. When\n  // O_NOFOLLOW is absent, the post-open fstat identity check below is the\n  // symlink-swap defense. O_NONBLOCK avoids blocking indefinitely if a path is\n  // swapped to a FIFO or another blocking special file before fstat rejects it.\n  return (\n    constants.O_RDONLY |\n    (constants.O_NOFOLLOW ?? 0) |\n    ((constants as { O_NONBLOCK?: number }).O_NONBLOCK ?? 0)\n  )\n}\n\nfunction normalizeSliceOffset(value: number, size: number): number {\n  if (!Number.isFinite(value)) throw new RangeError('FileSource slice offsets must be finite.')\n  const integer = Math.trunc(value)\n  const offset = integer < 0 ? size + integer : integer\n  return Math.min(Math.max(offset, 0), size)\n}\n\nfunction formatFilePath(path: FileSourcePath): string {\n  return path instanceof URL ? path.href : path\n}\n\nfunction identityFromStats(stats: FileStatsLike): FileIdentity {\n  return {\n    dev: stats.dev,\n    ino: stats.ino,\n    size: stats.size,\n    mtimeMs: stats.mtimeMs,\n    ctimeMs: stats.ctimeMs,\n  }\n}\n\nfunction assertStableIdentity(path: FileSourcePath, stats: FileStatsLike): void {\n  if (stats.dev === 0 && stats.ino === 0) {\n    throw new Error(\n      `FileSource: ${formatFilePath(path)} is on a filesystem that does not expose stable file identity.`,\n    )\n  }\n}\n\nfunction assertRegularFile(path: FileSourcePath, stats: FileStatsLike): void {\n  if (!stats.isFile()) {\n    throw new Error(`FileSource: ${formatFilePath(path)} is not a regular file.`)\n  }\n}\n\nfunction validatedIdentityFromStats(path: FileSourcePath, stats: FileStatsLike): FileIdentity {\n  assertRegularFile(path, stats)\n  if (shouldComparePosixFileIdentity()) assertStableIdentity(path, stats)\n  return identityFromStats(stats)\n}\n\nfunction assertSameIdentity(\n  path: FileSourcePath,\n  expected: FileIdentity,\n  actual: FileStatsLike,\n  when: string,\n): void {\n  if (shouldComparePosixFileIdentity()) assertStableIdentity(path, actual)\n  if (\n    shouldComparePosixFileIdentity() &&\n    (actual.dev !== expected.dev || actual.ino !== expected.ino)\n  ) {\n    throw new Error(`FileSource: ${formatFilePath(path)} changed ${when}.`)\n  }\n  if (actual.size !== expected.size || actual.mtimeMs !== expected.mtimeMs) {\n    throw new Error(`FileSource: ${formatFilePath(path)} was modified ${when}.`)\n  }\n  if (shouldComparePosixChangeTime() && actual.ctimeMs !== expected.ctimeMs) {\n    throw new Error(`FileSource: ${formatFilePath(path)} was modified ${when}.`)\n  }\n}\n\nfunction isWindows(): boolean {\n  if (fileSourceTestHooks.platform !== undefined) return fileSourceTestHooks.platform === 'win32'\n  const processLike = (globalThis as { process?: { platform?: string } }).process\n  return processLike?.platform === 'win32'\n}\n\nfunction shouldComparePosixFileIdentity(): boolean {\n  return !isWindows()\n}\n\nfunction shouldComparePosixChangeTime(): boolean {\n  return !isWindows()\n}\n\nfunction throwIfAborted(signal: AbortSignal | undefined): void {\n  if (signal === undefined || !signal.aborted) return\n  throw signal.reason ?? new DOMException('Aborted', 'AbortError')\n}\n\nfunction maxReadSize(): number {\n  return fileSourceTestHooks.maxReadSize ?? FILE_STREAM_CHUNK_SIZE\n}\n\n/* v8 ignore start -- Requires a file to pass identity checks and still EOF mid-range. */\nfunction rangeEndedEarlyError(path: FileSourcePath, offset: number, size: number): Error {\n  const end = offset + size\n  return new Error(\n    `FileSource: ${formatFilePath(path)} ended before byte range [${offset}, ${end}) was fully read.`,\n  )\n}\n/* v8 ignore stop */\n\nasync function openValidatedFile(\n  path: FileSourcePath,\n  identity: FileIdentity,\n): Promise<FileHandleLike> {\n  const open =\n    fileSourceTestHooks.openFile ??\n    (\n      (await import('node:fs/promises')) as {\n        open(path: FileSourcePath, flags: number): Promise<FileHandleLike>\n      }\n    ).open\n  let file: FileHandleLike\n  try {\n    file = await open(path, await fileOpenFlags())\n  } catch (err) {\n    const message = err instanceof Error ? err.message : String(err)\n    throw new Error(`FileSource: ${formatFilePath(path)} could not be opened: ${message}`)\n  }\n\n  try {\n    const stats = await file.stat()\n    assertRegularFile(path, stats)\n    assertSameIdentity(path, identity, stats, 'before read')\n    return file\n  } catch (err) {\n    /* v8 ignore next -- Cleanup failure is deliberately best-effort. */\n    await file.close().catch(() => {})\n    throw err\n  }\n}\n\nasync function lstatNodeFile(path: FileSourcePath): Promise<FileStatsLike> {\n  const { lstat } = (await import('node:fs/promises')) as {\n    lstat(path: FileSourcePath): Promise<FileStatsLike>\n  }\n  return lstat(path)\n}\n\nasync function readFileRange(\n  path: FileSourcePath,\n  identity: FileIdentity,\n  offset: number,\n  size: number,\n  signal?: AbortSignal,\n): Promise<Uint8Array> {\n  throwIfAborted(signal)\n  if (size === 0) {\n    await verifyFileIdentityForEmptyRead(path, identity, signal)\n    return new Uint8Array(0)\n  }\n\n  throwIfAborted(signal)\n  const file = await openValidatedFile(path, identity)\n  const data = new Uint8Array(size)\n  let filled = 0\n  try {\n    while (filled < data.byteLength) {\n      throwIfAborted(signal)\n      const length = Math.min(maxReadSize(), data.byteLength - filled)\n      const { bytesRead } = await file.read(data, filled, length, offset + filled)\n      if (bytesRead === 0) throw rangeEndedEarlyError(path, offset, size)\n      filled += bytesRead\n      await fileSourceTestHooks.afterReadIteration?.(filled)\n    }\n    throwIfAborted(signal)\n    const stats = await file.stat()\n    assertSameIdentity(path, identity, stats, 'while being read')\n    return data\n  } finally {\n    /* v8 ignore next -- Cleanup failure is deliberately best-effort. */\n    await file.close().catch(() => {})\n  }\n}\n\nasync function verifyFileIdentityForEmptyRead(\n  path: FileSourcePath,\n  identity: FileIdentity,\n  signal?: AbortSignal,\n): Promise<void> {\n  throwIfAborted(signal)\n  const file = await openValidatedFile(path, identity)\n  try {\n    throwIfAborted(signal)\n    return\n  } finally {\n    /* v8 ignore next -- Cleanup failure is deliberately best-effort. */\n    await file.close().catch(() => {})\n  }\n}\n\nfunction sliceFileRange(\n  path: FileSourcePath,\n  identity: FileIdentity,\n  offset: number,\n  size: number,\n  start: number,\n  end: number,\n): ContentSource {\n  const normalizedStart = normalizeSliceOffset(start, size)\n  const normalizedEnd = normalizeSliceOffset(end, size)\n  return new FileSliceSource(\n    path,\n    identity,\n    offset + normalizedStart,\n    Math.max(normalizedEnd - normalizedStart, 0),\n  )\n}\n\nfunction streamFileRange(\n  path: FileSourcePath,\n  identity: FileIdentity,\n  offset: number,\n  size: number,\n): ReadableStream<Uint8Array> {\n  let position = offset\n  let remaining = size\n  let verifiedEmpty = false\n  const abortController = new AbortController()\n\n  // Open per pull so abandoned public streams do not strand file handles or\n  // retain Windows locks. Each chunk still verifies identity around its read.\n  return new ReadableStream<Uint8Array>({\n    async pull(controller) {\n      try {\n        if (remaining === 0) {\n          if (!verifiedEmpty) {\n            verifiedEmpty = true\n            await verifyFileIdentityForEmptyRead(path, identity)\n          }\n          controller.close()\n          return\n        }\n\n        const length = Math.min(FILE_STREAM_CHUNK_SIZE, remaining)\n        const data = await readFileRange(path, identity, position, length, abortController.signal)\n        position += data.byteLength\n        remaining -= data.byteLength\n        controller.enqueue(data)\n        if (remaining === 0) controller.close()\n      } catch (err) {\n        controller.error(err)\n      }\n    },\n    cancel(reason) {\n      abortController.abort(reason)\n    },\n  })\n}\n\nasync function fileRangeToArrayBuffer(\n  path: FileSourcePath,\n  identity: FileIdentity,\n  offset: number,\n  size: number,\n  options: ToArrayBufferOptions = {},\n): Promise<ArrayBuffer> {\n  const data = await readFileRange(path, identity, offset, size, options.signal)\n  return data.buffer as ArrayBuffer\n}\n\nclass FileSliceSource implements ContentSource {\n  readonly canSlice = true\n\n  constructor(\n    private readonly path: FileSourcePath,\n    private readonly identity: FileIdentity,\n    private readonly offset: number,\n    readonly size: number,\n  ) {}\n\n  slice(start: number, end: number): ContentSource {\n    return sliceFileRange(this.path, this.identity, this.offset, this.size, start, end)\n  }\n\n  stream(): ReadableStream<Uint8Array> {\n    return streamFileRange(this.path, this.identity, this.offset, this.size)\n  }\n\n  toArrayBuffer(options: ToArrayBufferOptions = {}): Promise<ArrayBuffer> {\n    return fileRangeToArrayBuffer(this.path, this.identity, this.offset, this.size, options)\n  }\n}\n\n/**\n * ContentSource backed by a local filesystem path.\n *\n * `FileSource` is Node-only but safe to import in browser builds: it touches\n * Node filesystem APIs only when constructed or read. The constructor performs\n * synchronous filesystem validation so `size` is immediately available; request\n * handlers, sync loops, and other latency-sensitive code should use\n * {@link FileSource.fromPath}. Both paths capture a best-effort regular file\n * identity and reject a symlink as the final path component; parent directory\n * symlinks are followed by the operating system, so callers that constrain\n * paths under a trusted root should validate those parents separately. Reads\n * reject if the path is replaced, if the filesystem cannot report stable\n * identity on POSIX platforms, or if size/mtime/ctime changes before the\n * configured byte range is read. On Windows, reads avoid unreliable dev/inode\n * identity comparisons and validate size/mtime instead.\n * Slices preserve the captured identity, so multipart uploads can read\n * disjoint ranges without materialising the whole file in memory or following\n * later leaf path swaps.\n */\nexport class FileSource implements ContentSource {\n  /** Random-access: file ranges are read by absolute byte offset. */\n  readonly canSlice = true\n  /** File size captured at construction time. */\n  readonly size: number\n  private readonly path: FileSourcePath\n  private readonly identity: FileIdentity\n\n  /**\n   * Create a FileSource for a local file path.\n   * @param path - Local filesystem path or file URL.\n   *\n   * @throws If the runtime has no Node-compatible filesystem API.\n   * @throws If the path does not reference a regular non-symlink file.\n   * @throws If a POSIX filesystem cannot report stable file identity.\n   */\n  constructor(path: FileSourcePath)\n  /**\n   * Internal constructor path for async validation.\n   * @param path - Local filesystem path or file URL.\n   * @param internal - Module-private validated identity payload.\n   *\n   * @internal\n   */\n  constructor(path: FileSourcePath, internal?: FileSourceInternalOptions) {\n    const resolvedIdentity =\n      internal?.key === FILE_SOURCE_INTERNAL\n        ? internal.identity\n        : validatedIdentityFromStats(path, getNodeFsSync().lstatSync(path))\n    this.path = path\n    this.identity = resolvedIdentity\n    this.size = resolvedIdentity.size\n  }\n\n  /**\n   * Return a new file-backed source covering the specified byte range.\n   * @param start - The zero-based byte offset to begin the slice.\n   * @param end - The exclusive byte offset where the slice ends.\n   *\n   * @returns A new ContentSource representing the requested sub-range.\n   */\n  slice(start: number, end: number): ContentSource {\n    return sliceFileRange(this.path, this.identity, 0, this.size, start, end)\n  }\n\n  /**\n   * Open this file as a Web ReadableStream.\n   * @returns A ReadableStream that reads the file lazily.\n   */\n  stream(): ReadableStream<Uint8Array> {\n    return streamFileRange(this.path, this.identity, 0, this.size)\n  }\n\n  /**\n   * Read this file into an ArrayBuffer.\n   * @param options - Optional abort signal used while reading.\n   *\n   * @returns A promise resolving with the file bytes.\n   */\n  toArrayBuffer(options: { readonly signal?: AbortSignal } = {}): Promise<ArrayBuffer> {\n    return fileRangeToArrayBuffer(this.path, this.identity, 0, this.size, options)\n  }\n\n  /**\n   * Create a FileSource using asynchronous filesystem validation.\n   * @param path - Local filesystem path or file URL.\n   *\n   * @returns A FileSource bound to the validated file identity.\n   *\n   * @throws If the path does not reference a regular non-symlink file.\n   * @throws If a POSIX filesystem cannot report stable file identity.\n   */\n  static async fromPath(path: FileSourcePath): Promise<FileSource> {\n    const identity = validatedIdentityFromStats(path, await lstatNodeFile(path))\n    return constructFileSourceFromIdentity(path, identity)\n  }\n}\n\nfunction constructFileSourceFromIdentity(path: FileSourcePath, identity: FileIdentity): FileSource {\n  // The public overload is intentionally single-argument; Reflect.construct\n  // lets fromPath pass the module-private validated identity without exposing\n  // that constructor shape in the public type surface.\n  return Reflect.construct(FileSource, [\n    path,\n    { key: FILE_SOURCE_INTERNAL, identity },\n  ]) as FileSource\n}\n"],"mappings":"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"}
+{"version":3,"file":"file-source.cjs","names":[],"sources":["../../src/streams/file-source.ts"],"sourcesContent":["import type { ContentSource } from './source.ts'\n\nconst FILE_STREAM_CHUNK_SIZE = 16 * 1024 * 1024\n\n/** Filesystem path accepted by {@link FileSource}. */\nexport type FileSourcePath = string | URL\n\ninterface FileStatsLike {\n  readonly dev: number\n  readonly ino: number\n  readonly mode: number\n  readonly size: number\n  readonly mtimeMs: number\n  readonly ctimeMs: number\n  isFile(): boolean\n}\n\ninterface FileHandleLike {\n  read(\n    buffer: Uint8Array,\n    offset: number,\n    length: number,\n    position: number,\n  ): Promise<{ bytesRead: number }>\n  stat(): Promise<FileStatsLike>\n  close(): Promise<void>\n}\n\ninterface NodeFsSync {\n  lstatSync(path: FileSourcePath): FileStatsLike\n}\n\ninterface FileIdentity {\n  readonly dev: number\n  readonly ino: number\n  readonly size: number\n  readonly mtimeMs: number\n  readonly ctimeMs: number\n}\n\ninterface ToArrayBufferOptions {\n  readonly signal?: AbortSignal\n}\n\nconst FILE_SOURCE_INTERNAL = Symbol('FileSource.internal')\n\ninterface FileSourceInternalOptions {\n  readonly key: typeof FILE_SOURCE_INTERNAL\n  readonly identity: FileIdentity\n}\n\n/** @internal */\nexport const fileSourceTestHooks: {\n  afterReadIteration?: (filled: number) => Promise<void> | void\n  maxReadSize?: number\n  openFile?: (path: FileSourcePath, flags: number) => Promise<FileHandleLike>\n  platform?: string\n} = {}\n\nfunction getNodeFsSync(): NodeFsSync {\n  // FileSource exposes `size` synchronously, so the constructor cannot use the\n  // repo's usual `await import('node:...')` pattern for Node-only APIs. Keep the\n  // synchronous lookup here; async callers should prefer `FileSource.fromPath()`.\n  const processLike = (\n    globalThis as {\n      process?: { getBuiltinModule?: (id: string) => unknown }\n    }\n  ).process\n  const fs = processLike?.getBuiltinModule?.('node:fs')\n  if (!isNodeFsSync(fs)) {\n    throw new Error(\n      'FileSource constructor requires process.getBuiltinModule(\"node:fs\") with synchronous filesystem APIs; use FileSource.fromPath() when synchronous filesystem access is unavailable.',\n    )\n  }\n  return fs\n}\n\nfunction isNodeFsSync(value: unknown): value is NodeFsSync {\n  if (typeof value !== 'object' || value === null) return false\n  const candidate = value as Record<string, unknown>\n  return typeof candidate['lstatSync'] === 'function'\n}\n\nasync function fileOpenFlags(): Promise<number> {\n  const { constants } = await import('node:fs')\n  // O_NOFOLLOW and O_NONBLOCK are unavailable on some platforms. When\n  // O_NOFOLLOW is absent, the post-open fstat identity check below is the\n  // symlink-swap defense. O_NONBLOCK avoids blocking indefinitely if a path is\n  // swapped to a FIFO or another blocking special file before fstat rejects it.\n  return (\n    constants.O_RDONLY |\n    (constants.O_NOFOLLOW ?? 0) |\n    ((constants as { O_NONBLOCK?: number }).O_NONBLOCK ?? 0)\n  )\n}\n\nfunction normalizeSliceOffset(value: number, size: number): number {\n  if (!Number.isFinite(value)) throw new RangeError('FileSource slice offsets must be finite.')\n  const integer = Math.trunc(value)\n  const offset = integer < 0 ? size + integer : integer\n  return Math.min(Math.max(offset, 0), size)\n}\n\nfunction formatFilePath(path: FileSourcePath): string {\n  return path instanceof URL ? path.href : path\n}\n\nfunction identityFromStats(stats: FileStatsLike): FileIdentity {\n  return {\n    dev: stats.dev,\n    ino: stats.ino,\n    size: stats.size,\n    mtimeMs: stats.mtimeMs,\n    ctimeMs: stats.ctimeMs,\n  }\n}\n\nfunction assertStableIdentity(path: FileSourcePath, stats: FileStatsLike): void {\n  if (stats.dev === 0 && stats.ino === 0) {\n    throw new Error(\n      `FileSource: ${formatFilePath(path)} is on a filesystem that does not expose stable file identity.`,\n    )\n  }\n}\n\nfunction assertRegularFile(path: FileSourcePath, stats: FileStatsLike): void {\n  if (!stats.isFile()) {\n    throw new Error(`FileSource: ${formatFilePath(path)} is not a regular file.`)\n  }\n}\n\nfunction validatedIdentityFromStats(path: FileSourcePath, stats: FileStatsLike): FileIdentity {\n  assertRegularFile(path, stats)\n  if (shouldComparePosixFileIdentity()) assertStableIdentity(path, stats)\n  return identityFromStats(stats)\n}\n\nfunction assertSameIdentity(\n  path: FileSourcePath,\n  expected: FileIdentity,\n  actual: FileStatsLike,\n  when: string,\n): void {\n  if (shouldComparePosixFileIdentity()) assertStableIdentity(path, actual)\n  if (\n    shouldComparePosixFileIdentity() &&\n    (actual.dev !== expected.dev || actual.ino !== expected.ino)\n  ) {\n    throw new Error(`FileSource: ${formatFilePath(path)} changed ${when}.`)\n  }\n  if (actual.size !== expected.size || actual.mtimeMs !== expected.mtimeMs) {\n    throw new Error(`FileSource: ${formatFilePath(path)} was modified ${when}.`)\n  }\n  if (shouldComparePosixChangeTime() && actual.ctimeMs !== expected.ctimeMs) {\n    throw new Error(`FileSource: ${formatFilePath(path)} was modified ${when}.`)\n  }\n}\n\nfunction isWindows(): boolean {\n  if (fileSourceTestHooks.platform !== undefined) return fileSourceTestHooks.platform === 'win32'\n  const processLike = (globalThis as { process?: { platform?: string } }).process\n  return processLike?.platform === 'win32'\n}\n\nfunction shouldComparePosixFileIdentity(): boolean {\n  return !isWindows()\n}\n\nfunction shouldComparePosixChangeTime(): boolean {\n  return !isWindows()\n}\n\nfunction throwIfAborted(signal: AbortSignal | undefined): void {\n  if (signal === undefined || !signal.aborted) return\n  throw signal.reason ?? new DOMException('Aborted', 'AbortError')\n}\n\nfunction maxReadSize(): number {\n  return fileSourceTestHooks.maxReadSize ?? FILE_STREAM_CHUNK_SIZE\n}\n\n/* v8 ignore start -- Requires a file to pass identity checks and still EOF mid-range. */\nfunction rangeEndedEarlyError(path: FileSourcePath, offset: number, size: number): Error {\n  const end = offset + size\n  return new Error(\n    `FileSource: ${formatFilePath(path)} ended before byte range [${offset}, ${end}) was fully read.`,\n  )\n}\n/* v8 ignore stop */\n\nasync function openValidatedFile(\n  path: FileSourcePath,\n  identity: FileIdentity,\n): Promise<FileHandleLike> {\n  const open =\n    fileSourceTestHooks.openFile ??\n    (\n      (await import('node:fs/promises')) as {\n        open(path: FileSourcePath, flags: number): Promise<FileHandleLike>\n      }\n    ).open\n  let file: FileHandleLike\n  try {\n    file = await open(path, await fileOpenFlags())\n  } catch (err) {\n    const message = err instanceof Error ? err.message : String(err)\n    throw new Error(`FileSource: ${formatFilePath(path)} could not be opened: ${message}`)\n  }\n\n  try {\n    const stats = await file.stat()\n    assertRegularFile(path, stats)\n    assertSameIdentity(path, identity, stats, 'before read')\n    return file\n  } catch (err) {\n    /* v8 ignore next -- Cleanup failure is deliberately best-effort. */\n    await file.close().catch(() => {})\n    throw err\n  }\n}\n\nasync function lstatNodeFile(path: FileSourcePath): Promise<FileStatsLike> {\n  const { lstat } = (await import('node:fs/promises')) as {\n    lstat(path: FileSourcePath): Promise<FileStatsLike>\n  }\n  return lstat(path)\n}\n\nasync function readFileRange(\n  path: FileSourcePath,\n  identity: FileIdentity,\n  offset: number,\n  size: number,\n  signal?: AbortSignal,\n): Promise<Uint8Array> {\n  throwIfAborted(signal)\n  if (size === 0) {\n    await verifyFileIdentityForEmptyRead(path, identity, signal)\n    return new Uint8Array(0)\n  }\n\n  throwIfAborted(signal)\n  const file = await openValidatedFile(path, identity)\n  const data = new Uint8Array(size)\n  let filled = 0\n  try {\n    while (filled < data.byteLength) {\n      throwIfAborted(signal)\n      const length = Math.min(maxReadSize(), data.byteLength - filled)\n      const { bytesRead } = await file.read(data, filled, length, offset + filled)\n      if (bytesRead === 0) throw rangeEndedEarlyError(path, offset, size)\n      filled += bytesRead\n      await fileSourceTestHooks.afterReadIteration?.(filled)\n    }\n    throwIfAborted(signal)\n    const stats = await file.stat()\n    assertSameIdentity(path, identity, stats, 'while being read')\n    return data\n  } finally {\n    /* v8 ignore next -- Cleanup failure is deliberately best-effort. */\n    await file.close().catch(() => {})\n  }\n}\n\nasync function verifyFileIdentityForEmptyRead(\n  path: FileSourcePath,\n  identity: FileIdentity,\n  signal?: AbortSignal,\n): Promise<void> {\n  throwIfAborted(signal)\n  const file = await openValidatedFile(path, identity)\n  try {\n    throwIfAborted(signal)\n    return\n  } finally {\n    /* v8 ignore next -- Cleanup failure is deliberately best-effort. */\n    await file.close().catch(() => {})\n  }\n}\n\nfunction sliceFileRange(\n  path: FileSourcePath,\n  identity: FileIdentity,\n  offset: number,\n  size: number,\n  start: number,\n  end: number,\n): ContentSource {\n  const normalizedStart = normalizeSliceOffset(start, size)\n  const normalizedEnd = normalizeSliceOffset(end, size)\n  return new FileSliceSource(\n    path,\n    identity,\n    offset + normalizedStart,\n    Math.max(normalizedEnd - normalizedStart, 0),\n  )\n}\n\nfunction streamFileRange(\n  path: FileSourcePath,\n  identity: FileIdentity,\n  offset: number,\n  size: number,\n): ReadableStream<Uint8Array> {\n  let position = offset\n  let remaining = size\n  let verifiedEmpty = false\n  const abortController = new AbortController()\n\n  // Open per pull so abandoned public streams do not strand file handles or\n  // retain Windows locks. Each chunk still verifies identity around its read.\n  return new ReadableStream<Uint8Array>({\n    async pull(controller) {\n      try {\n        if (remaining === 0) {\n          if (!verifiedEmpty) {\n            verifiedEmpty = true\n            await verifyFileIdentityForEmptyRead(path, identity)\n          }\n          controller.close()\n          return\n        }\n\n        const length = Math.min(FILE_STREAM_CHUNK_SIZE, remaining)\n        const data = await readFileRange(path, identity, position, length, abortController.signal)\n        position += data.byteLength\n        remaining -= data.byteLength\n        controller.enqueue(data)\n        if (remaining === 0) controller.close()\n      } catch (err) {\n        controller.error(err)\n      }\n    },\n    cancel(reason) {\n      abortController.abort(reason)\n    },\n  })\n}\n\nasync function fileRangeToArrayBuffer(\n  path: FileSourcePath,\n  identity: FileIdentity,\n  offset: number,\n  size: number,\n  options: ToArrayBufferOptions = {},\n): Promise<ArrayBuffer> {\n  const data = await readFileRange(path, identity, offset, size, options.signal)\n  return data.buffer as ArrayBuffer\n}\n\nclass FileSliceSource implements ContentSource {\n  readonly canSlice = true\n\n  constructor(\n    private readonly path: FileSourcePath,\n    private readonly identity: FileIdentity,\n    private readonly offset: number,\n    readonly size: number,\n  ) {}\n\n  slice(start: number, end: number): ContentSource {\n    return sliceFileRange(this.path, this.identity, this.offset, this.size, start, end)\n  }\n\n  stream(): ReadableStream<Uint8Array> {\n    return streamFileRange(this.path, this.identity, this.offset, this.size)\n  }\n\n  toArrayBuffer(options: ToArrayBufferOptions = {}): Promise<ArrayBuffer> {\n    return fileRangeToArrayBuffer(this.path, this.identity, this.offset, this.size, options)\n  }\n}\n\n/**\n * ContentSource backed by a local filesystem path.\n *\n * `FileSource` is Node-only but safe to import in browser builds: it touches\n * Node filesystem APIs only when constructed or read. The constructor performs\n * synchronous filesystem validation so `size` is immediately available; request\n * handlers, sync loops, and other latency-sensitive code should use\n * {@link FileSource.fromPath}. Both paths capture a best-effort regular file\n * identity and reject a symlink as the final path component; parent directory\n * symlinks are followed by the operating system, so callers that constrain\n * paths under a trusted root should validate those parents separately. Reads\n * reject if the path is replaced, if the filesystem cannot report stable\n * identity on POSIX platforms, or if size/mtime/ctime changes before the\n * configured byte range is read. On Windows, reads avoid unreliable dev/inode\n * identity comparisons and validate size/mtime instead.\n * Slices preserve the captured identity, so multipart uploads can read\n * disjoint ranges without materialising the whole file in memory or following\n * later leaf path swaps.\n */\nexport class FileSource implements ContentSource {\n  /** Random-access: file ranges are read by absolute byte offset. */\n  readonly canSlice = true\n  /** File size captured at construction time. */\n  readonly size: number\n  private readonly path: FileSourcePath\n  private readonly identity: FileIdentity\n\n  /**\n   * Create a FileSource for a local file path.\n   * @param path - Local filesystem path or file URL.\n   *\n   * @throws If the runtime has no Node-compatible filesystem API.\n   * @throws If the path does not reference a regular non-symlink file.\n   * @throws If a POSIX filesystem cannot report stable file identity.\n   */\n  constructor(path: FileSourcePath)\n  /**\n   * Internal constructor path for async validation.\n   * @param path - Local filesystem path or file URL.\n   * @param internal - Module-private validated identity payload.\n   *\n   * @internal\n   */\n  constructor(path: FileSourcePath, internal?: FileSourceInternalOptions) {\n    const resolvedIdentity =\n      internal?.key === FILE_SOURCE_INTERNAL\n        ? internal.identity\n        : validatedIdentityFromStats(path, getNodeFsSync().lstatSync(path))\n    this.path = path\n    this.identity = resolvedIdentity\n    this.size = resolvedIdentity.size\n  }\n\n  /**\n   * Return a new file-backed source covering the specified byte range.\n   * @param start - The zero-based byte offset to begin the slice.\n   * @param end - The exclusive byte offset where the slice ends.\n   *\n   * @returns A new ContentSource representing the requested sub-range.\n   */\n  slice(start: number, end: number): ContentSource {\n    return sliceFileRange(this.path, this.identity, 0, this.size, start, end)\n  }\n\n  /**\n   * Open this file as a Web ReadableStream.\n   * @returns A ReadableStream that reads the file lazily.\n   */\n  stream(): ReadableStream<Uint8Array> {\n    return streamFileRange(this.path, this.identity, 0, this.size)\n  }\n\n  /**\n   * Read this file into an ArrayBuffer.\n   * @param options - Optional abort signal used while reading.\n   *\n   * @returns A promise resolving with the file bytes.\n   */\n  toArrayBuffer(options: { readonly signal?: AbortSignal } = {}): Promise<ArrayBuffer> {\n    return fileRangeToArrayBuffer(this.path, this.identity, 0, this.size, options)\n  }\n\n  /**\n   * Create a FileSource using asynchronous filesystem validation.\n   * @param path - Local filesystem path or file URL.\n   *\n   * @returns A FileSource bound to the validated file identity.\n   *\n   * @throws If the path does not reference a regular non-symlink file.\n   * @throws If a POSIX filesystem cannot report stable file identity.\n   */\n  static async fromPath(path: FileSourcePath): Promise<FileSource> {\n    const identity = validatedIdentityFromStats(path, await lstatNodeFile(path))\n    return constructFileSourceFromIdentity(path, identity)\n  }\n}\n\nfunction constructFileSourceFromIdentity(path: FileSourcePath, identity: FileIdentity): FileSource {\n  // The public overload is intentionally single-argument; Reflect.construct\n  // lets fromPath pass the module-private validated identity without exposing\n  // that constructor shape in the public type surface.\n  return Reflect.construct(FileSource, [\n    path,\n    { key: FILE_SOURCE_INTERNAL, identity },\n  ]) as FileSource\n}\n"],"mappings":"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"}

package/dist/streams/file-source.js

@@ -1,11 +1,11 @@
 //#region src/streams/file-source.ts
-var FILE_STREAM_CHUNK_SIZE = 16 * 1024 * 1024;
+var FILE_STREAM_CHUNK_SIZE = 16777216;
 var FILE_SOURCE_INTERNAL = Symbol("FileSource.internal");
 /** @internal */
 var fileSourceTestHooks = {};
 function getNodeFsSync() {
 	const fs = globalThis.process?.getBuiltinModule?.("node:fs");
-	if (!isNodeFsSync(fs)) throw new Error("FileSource constructor requires Node.js 22.3+ synchronous filesystem APIs; use FileSource.fromPath() when synchronous filesystem access is unavailable.");
+	if (!isNodeFsSync(fs)) throw new Error("FileSource constructor requires process.getBuiltinModule(\"node:fs\") with synchronous filesystem APIs; use FileSource.fromPath() when synchronous filesystem access is unavailable.");
 	return fs;
 }
 function isNodeFsSync(value) {

package/dist/streams/file-source.js.map

@@ -1 +1 @@
-{"version":3,"file":"file-source.js","names":[],"sources":["../../src/streams/file-source.ts"],"sourcesContent":["import type { ContentSource } from './source.ts'\n\nconst FILE_STREAM_CHUNK_SIZE = 16 * 1024 * 1024\n\n/** Filesystem path accepted by {@link FileSource}. */\nexport type FileSourcePath = string | URL\n\ninterface FileStatsLike {\n  readonly dev: number\n  readonly ino: number\n  readonly mode: number\n  readonly size: number\n  readonly mtimeMs: number\n  readonly ctimeMs: number\n  isFile(): boolean\n}\n\ninterface FileHandleLike {\n  read(\n    buffer: Uint8Array,\n    offset: number,\n    length: number,\n    position: number,\n  ): Promise<{ bytesRead: number }>\n  stat(): Promise<FileStatsLike>\n  close(): Promise<void>\n}\n\ninterface NodeFsSync {\n  lstatSync(path: FileSourcePath): FileStatsLike\n}\n\ninterface FileIdentity {\n  readonly dev: number\n  readonly ino: number\n  readonly size: number\n  readonly mtimeMs: number\n  readonly ctimeMs: number\n}\n\ninterface ToArrayBufferOptions {\n  readonly signal?: AbortSignal\n}\n\nconst FILE_SOURCE_INTERNAL = Symbol('FileSource.internal')\n\ninterface FileSourceInternalOptions {\n  readonly key: typeof FILE_SOURCE_INTERNAL\n  readonly identity: FileIdentity\n}\n\n/** @internal */\nexport const fileSourceTestHooks: {\n  afterReadIteration?: (filled: number) => Promise<void> | void\n  maxReadSize?: number\n  openFile?: (path: FileSourcePath, flags: number) => Promise<FileHandleLike>\n  platform?: string\n} = {}\n\nfunction getNodeFsSync(): NodeFsSync {\n  // FileSource exposes `size` synchronously, so the constructor cannot use the\n  // repo's usual `await import('node:...')` pattern for Node-only APIs. Keep the\n  // synchronous lookup here; async callers should prefer `FileSource.fromPath()`.\n  const processLike = (\n    globalThis as {\n      process?: { getBuiltinModule?: (id: string) => unknown }\n    }\n  ).process\n  const fs = processLike?.getBuiltinModule?.('node:fs')\n  if (!isNodeFsSync(fs)) {\n    throw new Error(\n      'FileSource constructor requires Node.js 22.3+ synchronous filesystem APIs; use FileSource.fromPath() when synchronous filesystem access is unavailable.',\n    )\n  }\n  return fs\n}\n\nfunction isNodeFsSync(value: unknown): value is NodeFsSync {\n  if (typeof value !== 'object' || value === null) return false\n  const candidate = value as Record<string, unknown>\n  return typeof candidate['lstatSync'] === 'function'\n}\n\nasync function fileOpenFlags(): Promise<number> {\n  const { constants } = await import('node:fs')\n  // O_NOFOLLOW and O_NONBLOCK are unavailable on some platforms. When\n  // O_NOFOLLOW is absent, the post-open fstat identity check below is the\n  // symlink-swap defense. O_NONBLOCK avoids blocking indefinitely if a path is\n  // swapped to a FIFO or another blocking special file before fstat rejects it.\n  return (\n    constants.O_RDONLY |\n    (constants.O_NOFOLLOW ?? 0) |\n    ((constants as { O_NONBLOCK?: number }).O_NONBLOCK ?? 0)\n  )\n}\n\nfunction normalizeSliceOffset(value: number, size: number): number {\n  if (!Number.isFinite(value)) throw new RangeError('FileSource slice offsets must be finite.')\n  const integer = Math.trunc(value)\n  const offset = integer < 0 ? size + integer : integer\n  return Math.min(Math.max(offset, 0), size)\n}\n\nfunction formatFilePath(path: FileSourcePath): string {\n  return path instanceof URL ? path.href : path\n}\n\nfunction identityFromStats(stats: FileStatsLike): FileIdentity {\n  return {\n    dev: stats.dev,\n    ino: stats.ino,\n    size: stats.size,\n    mtimeMs: stats.mtimeMs,\n    ctimeMs: stats.ctimeMs,\n  }\n}\n\nfunction assertStableIdentity(path: FileSourcePath, stats: FileStatsLike): void {\n  if (stats.dev === 0 && stats.ino === 0) {\n    throw new Error(\n      `FileSource: ${formatFilePath(path)} is on a filesystem that does not expose stable file identity.`,\n    )\n  }\n}\n\nfunction assertRegularFile(path: FileSourcePath, stats: FileStatsLike): void {\n  if (!stats.isFile()) {\n    throw new Error(`FileSource: ${formatFilePath(path)} is not a regular file.`)\n  }\n}\n\nfunction validatedIdentityFromStats(path: FileSourcePath, stats: FileStatsLike): FileIdentity {\n  assertRegularFile(path, stats)\n  if (shouldComparePosixFileIdentity()) assertStableIdentity(path, stats)\n  return identityFromStats(stats)\n}\n\nfunction assertSameIdentity(\n  path: FileSourcePath,\n  expected: FileIdentity,\n  actual: FileStatsLike,\n  when: string,\n): void {\n  if (shouldComparePosixFileIdentity()) assertStableIdentity(path, actual)\n  if (\n    shouldComparePosixFileIdentity() &&\n    (actual.dev !== expected.dev || actual.ino !== expected.ino)\n  ) {\n    throw new Error(`FileSource: ${formatFilePath(path)} changed ${when}.`)\n  }\n  if (actual.size !== expected.size || actual.mtimeMs !== expected.mtimeMs) {\n    throw new Error(`FileSource: ${formatFilePath(path)} was modified ${when}.`)\n  }\n  if (shouldComparePosixChangeTime() && actual.ctimeMs !== expected.ctimeMs) {\n    throw new Error(`FileSource: ${formatFilePath(path)} was modified ${when}.`)\n  }\n}\n\nfunction isWindows(): boolean {\n  if (fileSourceTestHooks.platform !== undefined) return fileSourceTestHooks.platform === 'win32'\n  const processLike = (globalThis as { process?: { platform?: string } }).process\n  return processLike?.platform === 'win32'\n}\n\nfunction shouldComparePosixFileIdentity(): boolean {\n  return !isWindows()\n}\n\nfunction shouldComparePosixChangeTime(): boolean {\n  return !isWindows()\n}\n\nfunction throwIfAborted(signal: AbortSignal | undefined): void {\n  if (signal === undefined || !signal.aborted) return\n  throw signal.reason ?? new DOMException('Aborted', 'AbortError')\n}\n\nfunction maxReadSize(): number {\n  return fileSourceTestHooks.maxReadSize ?? FILE_STREAM_CHUNK_SIZE\n}\n\n/* v8 ignore start -- Requires a file to pass identity checks and still EOF mid-range. */\nfunction rangeEndedEarlyError(path: FileSourcePath, offset: number, size: number): Error {\n  const end = offset + size\n  return new Error(\n    `FileSource: ${formatFilePath(path)} ended before byte range [${offset}, ${end}) was fully read.`,\n  )\n}\n/* v8 ignore stop */\n\nasync function openValidatedFile(\n  path: FileSourcePath,\n  identity: FileIdentity,\n): Promise<FileHandleLike> {\n  const open =\n    fileSourceTestHooks.openFile ??\n    (\n      (await import('node:fs/promises')) as {\n        open(path: FileSourcePath, flags: number): Promise<FileHandleLike>\n      }\n    ).open\n  let file: FileHandleLike\n  try {\n    file = await open(path, await fileOpenFlags())\n  } catch (err) {\n    const message = err instanceof Error ? err.message : String(err)\n    throw new Error(`FileSource: ${formatFilePath(path)} could not be opened: ${message}`)\n  }\n\n  try {\n    const stats = await file.stat()\n    assertRegularFile(path, stats)\n    assertSameIdentity(path, identity, stats, 'before read')\n    return file\n  } catch (err) {\n    /* v8 ignore next -- Cleanup failure is deliberately best-effort. */\n    await file.close().catch(() => {})\n    throw err\n  }\n}\n\nasync function lstatNodeFile(path: FileSourcePath): Promise<FileStatsLike> {\n  const { lstat } = (await import('node:fs/promises')) as {\n    lstat(path: FileSourcePath): Promise<FileStatsLike>\n  }\n  return lstat(path)\n}\n\nasync function readFileRange(\n  path: FileSourcePath,\n  identity: FileIdentity,\n  offset: number,\n  size: number,\n  signal?: AbortSignal,\n): Promise<Uint8Array> {\n  throwIfAborted(signal)\n  if (size === 0) {\n    await verifyFileIdentityForEmptyRead(path, identity, signal)\n    return new Uint8Array(0)\n  }\n\n  throwIfAborted(signal)\n  const file = await openValidatedFile(path, identity)\n  const data = new Uint8Array(size)\n  let filled = 0\n  try {\n    while (filled < data.byteLength) {\n      throwIfAborted(signal)\n      const length = Math.min(maxReadSize(), data.byteLength - filled)\n      const { bytesRead } = await file.read(data, filled, length, offset + filled)\n      if (bytesRead === 0) throw rangeEndedEarlyError(path, offset, size)\n      filled += bytesRead\n      await fileSourceTestHooks.afterReadIteration?.(filled)\n    }\n    throwIfAborted(signal)\n    const stats = await file.stat()\n    assertSameIdentity(path, identity, stats, 'while being read')\n    return data\n  } finally {\n    /* v8 ignore next -- Cleanup failure is deliberately best-effort. */\n    await file.close().catch(() => {})\n  }\n}\n\nasync function verifyFileIdentityForEmptyRead(\n  path: FileSourcePath,\n  identity: FileIdentity,\n  signal?: AbortSignal,\n): Promise<void> {\n  throwIfAborted(signal)\n  const file = await openValidatedFile(path, identity)\n  try {\n    throwIfAborted(signal)\n    return\n  } finally {\n    /* v8 ignore next -- Cleanup failure is deliberately best-effort. */\n    await file.close().catch(() => {})\n  }\n}\n\nfunction sliceFileRange(\n  path: FileSourcePath,\n  identity: FileIdentity,\n  offset: number,\n  size: number,\n  start: number,\n  end: number,\n): ContentSource {\n  const normalizedStart = normalizeSliceOffset(start, size)\n  const normalizedEnd = normalizeSliceOffset(end, size)\n  return new FileSliceSource(\n    path,\n    identity,\n    offset + normalizedStart,\n    Math.max(normalizedEnd - normalizedStart, 0),\n  )\n}\n\nfunction streamFileRange(\n  path: FileSourcePath,\n  identity: FileIdentity,\n  offset: number,\n  size: number,\n): ReadableStream<Uint8Array> {\n  let position = offset\n  let remaining = size\n  let verifiedEmpty = false\n  const abortController = new AbortController()\n\n  // Open per pull so abandoned public streams do not strand file handles or\n  // retain Windows locks. Each chunk still verifies identity around its read.\n  return new ReadableStream<Uint8Array>({\n    async pull(controller) {\n      try {\n        if (remaining === 0) {\n          if (!verifiedEmpty) {\n            verifiedEmpty = true\n            await verifyFileIdentityForEmptyRead(path, identity)\n          }\n          controller.close()\n          return\n        }\n\n        const length = Math.min(FILE_STREAM_CHUNK_SIZE, remaining)\n        const data = await readFileRange(path, identity, position, length, abortController.signal)\n        position += data.byteLength\n        remaining -= data.byteLength\n        controller.enqueue(data)\n        if (remaining === 0) controller.close()\n      } catch (err) {\n        controller.error(err)\n      }\n    },\n    cancel(reason) {\n      abortController.abort(reason)\n    },\n  })\n}\n\nasync function fileRangeToArrayBuffer(\n  path: FileSourcePath,\n  identity: FileIdentity,\n  offset: number,\n  size: number,\n  options: ToArrayBufferOptions = {},\n): Promise<ArrayBuffer> {\n  const data = await readFileRange(path, identity, offset, size, options.signal)\n  return data.buffer as ArrayBuffer\n}\n\nclass FileSliceSource implements ContentSource {\n  readonly canSlice = true\n\n  constructor(\n    private readonly path: FileSourcePath,\n    private readonly identity: FileIdentity,\n    private readonly offset: number,\n    readonly size: number,\n  ) {}\n\n  slice(start: number, end: number): ContentSource {\n    return sliceFileRange(this.path, this.identity, this.offset, this.size, start, end)\n  }\n\n  stream(): ReadableStream<Uint8Array> {\n    return streamFileRange(this.path, this.identity, this.offset, this.size)\n  }\n\n  toArrayBuffer(options: ToArrayBufferOptions = {}): Promise<ArrayBuffer> {\n    return fileRangeToArrayBuffer(this.path, this.identity, this.offset, this.size, options)\n  }\n}\n\n/**\n * ContentSource backed by a local filesystem path.\n *\n * `FileSource` is Node-only but safe to import in browser builds: it touches\n * Node filesystem APIs only when constructed or read. The constructor performs\n * synchronous filesystem validation so `size` is immediately available; request\n * handlers, sync loops, and other latency-sensitive code should use\n * {@link FileSource.fromPath}. Both paths capture a best-effort regular file\n * identity and reject a symlink as the final path component; parent directory\n * symlinks are followed by the operating system, so callers that constrain\n * paths under a trusted root should validate those parents separately. Reads\n * reject if the path is replaced, if the filesystem cannot report stable\n * identity on POSIX platforms, or if size/mtime/ctime changes before the\n * configured byte range is read. On Windows, reads avoid unreliable dev/inode\n * identity comparisons and validate size/mtime instead.\n * Slices preserve the captured identity, so multipart uploads can read\n * disjoint ranges without materialising the whole file in memory or following\n * later leaf path swaps.\n */\nexport class FileSource implements ContentSource {\n  /** Random-access: file ranges are read by absolute byte offset. */\n  readonly canSlice = true\n  /** File size captured at construction time. */\n  readonly size: number\n  private readonly path: FileSourcePath\n  private readonly identity: FileIdentity\n\n  /**\n   * Create a FileSource for a local file path.\n   * @param path - Local filesystem path or file URL.\n   *\n   * @throws If the runtime has no Node-compatible filesystem API.\n   * @throws If the path does not reference a regular non-symlink file.\n   * @throws If a POSIX filesystem cannot report stable file identity.\n   */\n  constructor(path: FileSourcePath)\n  /**\n   * Internal constructor path for async validation.\n   * @param path - Local filesystem path or file URL.\n   * @param internal - Module-private validated identity payload.\n   *\n   * @internal\n   */\n  constructor(path: FileSourcePath, internal?: FileSourceInternalOptions) {\n    const resolvedIdentity =\n      internal?.key === FILE_SOURCE_INTERNAL\n        ? internal.identity\n        : validatedIdentityFromStats(path, getNodeFsSync().lstatSync(path))\n    this.path = path\n    this.identity = resolvedIdentity\n    this.size = resolvedIdentity.size\n  }\n\n  /**\n   * Return a new file-backed source covering the specified byte range.\n   * @param start - The zero-based byte offset to begin the slice.\n   * @param end - The exclusive byte offset where the slice ends.\n   *\n   * @returns A new ContentSource representing the requested sub-range.\n   */\n  slice(start: number, end: number): ContentSource {\n    return sliceFileRange(this.path, this.identity, 0, this.size, start, end)\n  }\n\n  /**\n   * Open this file as a Web ReadableStream.\n   * @returns A ReadableStream that reads the file lazily.\n   */\n  stream(): ReadableStream<Uint8Array> {\n    return streamFileRange(this.path, this.identity, 0, this.size)\n  }\n\n  /**\n   * Read this file into an ArrayBuffer.\n   * @param options - Optional abort signal used while reading.\n   *\n   * @returns A promise resolving with the file bytes.\n   */\n  toArrayBuffer(options: { readonly signal?: AbortSignal } = {}): Promise<ArrayBuffer> {\n    return fileRangeToArrayBuffer(this.path, this.identity, 0, this.size, options)\n  }\n\n  /**\n   * Create a FileSource using asynchronous filesystem validation.\n   * @param path - Local filesystem path or file URL.\n   *\n   * @returns A FileSource bound to the validated file identity.\n   *\n   * @throws If the path does not reference a regular non-symlink file.\n   * @throws If a POSIX filesystem cannot report stable file identity.\n   */\n  static async fromPath(path: FileSourcePath): Promise<FileSource> {\n    const identity = validatedIdentityFromStats(path, await lstatNodeFile(path))\n    return constructFileSourceFromIdentity(path, identity)\n  }\n}\n\nfunction constructFileSourceFromIdentity(path: FileSourcePath, identity: FileIdentity): FileSource {\n  // The public overload is intentionally single-argument; Reflect.construct\n  // lets fromPath pass the module-private validated identity without exposing\n  // that constructor shape in the public type surface.\n  return Reflect.construct(FileSource, [\n    path,\n    { key: FILE_SOURCE_INTERNAL, identity },\n  ]) as FileSource\n}\n"],"mappings":"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"}
+{"version":3,"file":"file-source.js","names":[],"sources":["../../src/streams/file-source.ts"],"sourcesContent":["import type { ContentSource } from './source.ts'\n\nconst FILE_STREAM_CHUNK_SIZE = 16 * 1024 * 1024\n\n/** Filesystem path accepted by {@link FileSource}. */\nexport type FileSourcePath = string | URL\n\ninterface FileStatsLike {\n  readonly dev: number\n  readonly ino: number\n  readonly mode: number\n  readonly size: number\n  readonly mtimeMs: number\n  readonly ctimeMs: number\n  isFile(): boolean\n}\n\ninterface FileHandleLike {\n  read(\n    buffer: Uint8Array,\n    offset: number,\n    length: number,\n    position: number,\n  ): Promise<{ bytesRead: number }>\n  stat(): Promise<FileStatsLike>\n  close(): Promise<void>\n}\n\ninterface NodeFsSync {\n  lstatSync(path: FileSourcePath): FileStatsLike\n}\n\ninterface FileIdentity {\n  readonly dev: number\n  readonly ino: number\n  readonly size: number\n  readonly mtimeMs: number\n  readonly ctimeMs: number\n}\n\ninterface ToArrayBufferOptions {\n  readonly signal?: AbortSignal\n}\n\nconst FILE_SOURCE_INTERNAL = Symbol('FileSource.internal')\n\ninterface FileSourceInternalOptions {\n  readonly key: typeof FILE_SOURCE_INTERNAL\n  readonly identity: FileIdentity\n}\n\n/** @internal */\nexport const fileSourceTestHooks: {\n  afterReadIteration?: (filled: number) => Promise<void> | void\n  maxReadSize?: number\n  openFile?: (path: FileSourcePath, flags: number) => Promise<FileHandleLike>\n  platform?: string\n} = {}\n\nfunction getNodeFsSync(): NodeFsSync {\n  // FileSource exposes `size` synchronously, so the constructor cannot use the\n  // repo's usual `await import('node:...')` pattern for Node-only APIs. Keep the\n  // synchronous lookup here; async callers should prefer `FileSource.fromPath()`.\n  const processLike = (\n    globalThis as {\n      process?: { getBuiltinModule?: (id: string) => unknown }\n    }\n  ).process\n  const fs = processLike?.getBuiltinModule?.('node:fs')\n  if (!isNodeFsSync(fs)) {\n    throw new Error(\n      'FileSource constructor requires process.getBuiltinModule(\"node:fs\") with synchronous filesystem APIs; use FileSource.fromPath() when synchronous filesystem access is unavailable.',\n    )\n  }\n  return fs\n}\n\nfunction isNodeFsSync(value: unknown): value is NodeFsSync {\n  if (typeof value !== 'object' || value === null) return false\n  const candidate = value as Record<string, unknown>\n  return typeof candidate['lstatSync'] === 'function'\n}\n\nasync function fileOpenFlags(): Promise<number> {\n  const { constants } = await import('node:fs')\n  // O_NOFOLLOW and O_NONBLOCK are unavailable on some platforms. When\n  // O_NOFOLLOW is absent, the post-open fstat identity check below is the\n  // symlink-swap defense. O_NONBLOCK avoids blocking indefinitely if a path is\n  // swapped to a FIFO or another blocking special file before fstat rejects it.\n  return (\n    constants.O_RDONLY |\n    (constants.O_NOFOLLOW ?? 0) |\n    ((constants as { O_NONBLOCK?: number }).O_NONBLOCK ?? 0)\n  )\n}\n\nfunction normalizeSliceOffset(value: number, size: number): number {\n  if (!Number.isFinite(value)) throw new RangeError('FileSource slice offsets must be finite.')\n  const integer = Math.trunc(value)\n  const offset = integer < 0 ? size + integer : integer\n  return Math.min(Math.max(offset, 0), size)\n}\n\nfunction formatFilePath(path: FileSourcePath): string {\n  return path instanceof URL ? path.href : path\n}\n\nfunction identityFromStats(stats: FileStatsLike): FileIdentity {\n  return {\n    dev: stats.dev,\n    ino: stats.ino,\n    size: stats.size,\n    mtimeMs: stats.mtimeMs,\n    ctimeMs: stats.ctimeMs,\n  }\n}\n\nfunction assertStableIdentity(path: FileSourcePath, stats: FileStatsLike): void {\n  if (stats.dev === 0 && stats.ino === 0) {\n    throw new Error(\n      `FileSource: ${formatFilePath(path)} is on a filesystem that does not expose stable file identity.`,\n    )\n  }\n}\n\nfunction assertRegularFile(path: FileSourcePath, stats: FileStatsLike): void {\n  if (!stats.isFile()) {\n    throw new Error(`FileSource: ${formatFilePath(path)} is not a regular file.`)\n  }\n}\n\nfunction validatedIdentityFromStats(path: FileSourcePath, stats: FileStatsLike): FileIdentity {\n  assertRegularFile(path, stats)\n  if (shouldComparePosixFileIdentity()) assertStableIdentity(path, stats)\n  return identityFromStats(stats)\n}\n\nfunction assertSameIdentity(\n  path: FileSourcePath,\n  expected: FileIdentity,\n  actual: FileStatsLike,\n  when: string,\n): void {\n  if (shouldComparePosixFileIdentity()) assertStableIdentity(path, actual)\n  if (\n    shouldComparePosixFileIdentity() &&\n    (actual.dev !== expected.dev || actual.ino !== expected.ino)\n  ) {\n    throw new Error(`FileSource: ${formatFilePath(path)} changed ${when}.`)\n  }\n  if (actual.size !== expected.size || actual.mtimeMs !== expected.mtimeMs) {\n    throw new Error(`FileSource: ${formatFilePath(path)} was modified ${when}.`)\n  }\n  if (shouldComparePosixChangeTime() && actual.ctimeMs !== expected.ctimeMs) {\n    throw new Error(`FileSource: ${formatFilePath(path)} was modified ${when}.`)\n  }\n}\n\nfunction isWindows(): boolean {\n  if (fileSourceTestHooks.platform !== undefined) return fileSourceTestHooks.platform === 'win32'\n  const processLike = (globalThis as { process?: { platform?: string } }).process\n  return processLike?.platform === 'win32'\n}\n\nfunction shouldComparePosixFileIdentity(): boolean {\n  return !isWindows()\n}\n\nfunction shouldComparePosixChangeTime(): boolean {\n  return !isWindows()\n}\n\nfunction throwIfAborted(signal: AbortSignal | undefined): void {\n  if (signal === undefined || !signal.aborted) return\n  throw signal.reason ?? new DOMException('Aborted', 'AbortError')\n}\n\nfunction maxReadSize(): number {\n  return fileSourceTestHooks.maxReadSize ?? FILE_STREAM_CHUNK_SIZE\n}\n\n/* v8 ignore start -- Requires a file to pass identity checks and still EOF mid-range. */\nfunction rangeEndedEarlyError(path: FileSourcePath, offset: number, size: number): Error {\n  const end = offset + size\n  return new Error(\n    `FileSource: ${formatFilePath(path)} ended before byte range [${offset}, ${end}) was fully read.`,\n  )\n}\n/* v8 ignore stop */\n\nasync function openValidatedFile(\n  path: FileSourcePath,\n  identity: FileIdentity,\n): Promise<FileHandleLike> {\n  const open =\n    fileSourceTestHooks.openFile ??\n    (\n      (await import('node:fs/promises')) as {\n        open(path: FileSourcePath, flags: number): Promise<FileHandleLike>\n      }\n    ).open\n  let file: FileHandleLike\n  try {\n    file = await open(path, await fileOpenFlags())\n  } catch (err) {\n    const message = err instanceof Error ? err.message : String(err)\n    throw new Error(`FileSource: ${formatFilePath(path)} could not be opened: ${message}`)\n  }\n\n  try {\n    const stats = await file.stat()\n    assertRegularFile(path, stats)\n    assertSameIdentity(path, identity, stats, 'before read')\n    return file\n  } catch (err) {\n    /* v8 ignore next -- Cleanup failure is deliberately best-effort. */\n    await file.close().catch(() => {})\n    throw err\n  }\n}\n\nasync function lstatNodeFile(path: FileSourcePath): Promise<FileStatsLike> {\n  const { lstat } = (await import('node:fs/promises')) as {\n    lstat(path: FileSourcePath): Promise<FileStatsLike>\n  }\n  return lstat(path)\n}\n\nasync function readFileRange(\n  path: FileSourcePath,\n  identity: FileIdentity,\n  offset: number,\n  size: number,\n  signal?: AbortSignal,\n): Promise<Uint8Array> {\n  throwIfAborted(signal)\n  if (size === 0) {\n    await verifyFileIdentityForEmptyRead(path, identity, signal)\n    return new Uint8Array(0)\n  }\n\n  throwIfAborted(signal)\n  const file = await openValidatedFile(path, identity)\n  const data = new Uint8Array(size)\n  let filled = 0\n  try {\n    while (filled < data.byteLength) {\n      throwIfAborted(signal)\n      const length = Math.min(maxReadSize(), data.byteLength - filled)\n      const { bytesRead } = await file.read(data, filled, length, offset + filled)\n      if (bytesRead === 0) throw rangeEndedEarlyError(path, offset, size)\n      filled += bytesRead\n      await fileSourceTestHooks.afterReadIteration?.(filled)\n    }\n    throwIfAborted(signal)\n    const stats = await file.stat()\n    assertSameIdentity(path, identity, stats, 'while being read')\n    return data\n  } finally {\n    /* v8 ignore next -- Cleanup failure is deliberately best-effort. */\n    await file.close().catch(() => {})\n  }\n}\n\nasync function verifyFileIdentityForEmptyRead(\n  path: FileSourcePath,\n  identity: FileIdentity,\n  signal?: AbortSignal,\n): Promise<void> {\n  throwIfAborted(signal)\n  const file = await openValidatedFile(path, identity)\n  try {\n    throwIfAborted(signal)\n    return\n  } finally {\n    /* v8 ignore next -- Cleanup failure is deliberately best-effort. */\n    await file.close().catch(() => {})\n  }\n}\n\nfunction sliceFileRange(\n  path: FileSourcePath,\n  identity: FileIdentity,\n  offset: number,\n  size: number,\n  start: number,\n  end: number,\n): ContentSource {\n  const normalizedStart = normalizeSliceOffset(start, size)\n  const normalizedEnd = normalizeSliceOffset(end, size)\n  return new FileSliceSource(\n    path,\n    identity,\n    offset + normalizedStart,\n    Math.max(normalizedEnd - normalizedStart, 0),\n  )\n}\n\nfunction streamFileRange(\n  path: FileSourcePath,\n  identity: FileIdentity,\n  offset: number,\n  size: number,\n): ReadableStream<Uint8Array> {\n  let position = offset\n  let remaining = size\n  let verifiedEmpty = false\n  const abortController = new AbortController()\n\n  // Open per pull so abandoned public streams do not strand file handles or\n  // retain Windows locks. Each chunk still verifies identity around its read.\n  return new ReadableStream<Uint8Array>({\n    async pull(controller) {\n      try {\n        if (remaining === 0) {\n          if (!verifiedEmpty) {\n            verifiedEmpty = true\n            await verifyFileIdentityForEmptyRead(path, identity)\n          }\n          controller.close()\n          return\n        }\n\n        const length = Math.min(FILE_STREAM_CHUNK_SIZE, remaining)\n        const data = await readFileRange(path, identity, position, length, abortController.signal)\n        position += data.byteLength\n        remaining -= data.byteLength\n        controller.enqueue(data)\n        if (remaining === 0) controller.close()\n      } catch (err) {\n        controller.error(err)\n      }\n    },\n    cancel(reason) {\n      abortController.abort(reason)\n    },\n  })\n}\n\nasync function fileRangeToArrayBuffer(\n  path: FileSourcePath,\n  identity: FileIdentity,\n  offset: number,\n  size: number,\n  options: ToArrayBufferOptions = {},\n): Promise<ArrayBuffer> {\n  const data = await readFileRange(path, identity, offset, size, options.signal)\n  return data.buffer as ArrayBuffer\n}\n\nclass FileSliceSource implements ContentSource {\n  readonly canSlice = true\n\n  constructor(\n    private readonly path: FileSourcePath,\n    private readonly identity: FileIdentity,\n    private readonly offset: number,\n    readonly size: number,\n  ) {}\n\n  slice(start: number, end: number): ContentSource {\n    return sliceFileRange(this.path, this.identity, this.offset, this.size, start, end)\n  }\n\n  stream(): ReadableStream<Uint8Array> {\n    return streamFileRange(this.path, this.identity, this.offset, this.size)\n  }\n\n  toArrayBuffer(options: ToArrayBufferOptions = {}): Promise<ArrayBuffer> {\n    return fileRangeToArrayBuffer(this.path, this.identity, this.offset, this.size, options)\n  }\n}\n\n/**\n * ContentSource backed by a local filesystem path.\n *\n * `FileSource` is Node-only but safe to import in browser builds: it touches\n * Node filesystem APIs only when constructed or read. The constructor performs\n * synchronous filesystem validation so `size` is immediately available; request\n * handlers, sync loops, and other latency-sensitive code should use\n * {@link FileSource.fromPath}. Both paths capture a best-effort regular file\n * identity and reject a symlink as the final path component; parent directory\n * symlinks are followed by the operating system, so callers that constrain\n * paths under a trusted root should validate those parents separately. Reads\n * reject if the path is replaced, if the filesystem cannot report stable\n * identity on POSIX platforms, or if size/mtime/ctime changes before the\n * configured byte range is read. On Windows, reads avoid unreliable dev/inode\n * identity comparisons and validate size/mtime instead.\n * Slices preserve the captured identity, so multipart uploads can read\n * disjoint ranges without materialising the whole file in memory or following\n * later leaf path swaps.\n */\nexport class FileSource implements ContentSource {\n  /** Random-access: file ranges are read by absolute byte offset. */\n  readonly canSlice = true\n  /** File size captured at construction time. */\n  readonly size: number\n  private readonly path: FileSourcePath\n  private readonly identity: FileIdentity\n\n  /**\n   * Create a FileSource for a local file path.\n   * @param path - Local filesystem path or file URL.\n   *\n   * @throws If the runtime has no Node-compatible filesystem API.\n   * @throws If the path does not reference a regular non-symlink file.\n   * @throws If a POSIX filesystem cannot report stable file identity.\n   */\n  constructor(path: FileSourcePath)\n  /**\n   * Internal constructor path for async validation.\n   * @param path - Local filesystem path or file URL.\n   * @param internal - Module-private validated identity payload.\n   *\n   * @internal\n   */\n  constructor(path: FileSourcePath, internal?: FileSourceInternalOptions) {\n    const resolvedIdentity =\n      internal?.key === FILE_SOURCE_INTERNAL\n        ? internal.identity\n        : validatedIdentityFromStats(path, getNodeFsSync().lstatSync(path))\n    this.path = path\n    this.identity = resolvedIdentity\n    this.size = resolvedIdentity.size\n  }\n\n  /**\n   * Return a new file-backed source covering the specified byte range.\n   * @param start - The zero-based byte offset to begin the slice.\n   * @param end - The exclusive byte offset where the slice ends.\n   *\n   * @returns A new ContentSource representing the requested sub-range.\n   */\n  slice(start: number, end: number): ContentSource {\n    return sliceFileRange(this.path, this.identity, 0, this.size, start, end)\n  }\n\n  /**\n   * Open this file as a Web ReadableStream.\n   * @returns A ReadableStream that reads the file lazily.\n   */\n  stream(): ReadableStream<Uint8Array> {\n    return streamFileRange(this.path, this.identity, 0, this.size)\n  }\n\n  /**\n   * Read this file into an ArrayBuffer.\n   * @param options - Optional abort signal used while reading.\n   *\n   * @returns A promise resolving with the file bytes.\n   */\n  toArrayBuffer(options: { readonly signal?: AbortSignal } = {}): Promise<ArrayBuffer> {\n    return fileRangeToArrayBuffer(this.path, this.identity, 0, this.size, options)\n  }\n\n  /**\n   * Create a FileSource using asynchronous filesystem validation.\n   * @param path - Local filesystem path or file URL.\n   *\n   * @returns A FileSource bound to the validated file identity.\n   *\n   * @throws If the path does not reference a regular non-symlink file.\n   * @throws If a POSIX filesystem cannot report stable file identity.\n   */\n  static async fromPath(path: FileSourcePath): Promise<FileSource> {\n    const identity = validatedIdentityFromStats(path, await lstatNodeFile(path))\n    return constructFileSourceFromIdentity(path, identity)\n  }\n}\n\nfunction constructFileSourceFromIdentity(path: FileSourcePath, identity: FileIdentity): FileSource {\n  // The public overload is intentionally single-argument; Reflect.construct\n  // lets fromPath pass the module-private validated identity without exposing\n  // that constructor shape in the public type surface.\n  return Reflect.construct(FileSource, [\n    path,\n    { key: FILE_SOURCE_INTERNAL, identity },\n  ]) as FileSource\n}\n"],"mappings":"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"}