transloadit 4.13.1 → 5.0.0

package/src/alphalib/errors.ts

@@ -1,4 +1,4 @@
-import { getRecordProperty, isRecord } from './object.ts'
+import { getRecordProperty, isPresent, isRecord } from './object.ts'
 
 export function normalizeError(err: unknown): Error {
   if (err instanceof Error) {
@@ -8,26 +8,147 @@ export function normalizeError(err: unknown): Error {
   return new Error(`Was thrown a non-error: ${String(err)}`, { cause: err })
 }
 
+/** Log a normalized terminal error and stop the current CLI process. */
+export function exitWithError(error: unknown): never {
+  console.error(normalizeError(error))
+  process.exit(1)
+}
+
 export function getErrorMessage(err: unknown): string {
   return err instanceof Error ? err.message : String(err)
 }
 
-export function getErrorMessageWithCauses(err: unknown): string {
-  if (err instanceof AggregateError) {
-    return [err.message, ...err.errors.map((error) => getErrorMessageWithCauses(error))]
-      .filter(Boolean)
-      .join('\n')
+interface ErrorBranchSummary {
+  issueCount: number
+  messages: string[]
+  stackFrames: string[]
+}
+
+/** Cycle-safe summary of unique errors and non-error values in one error graph. */
+export interface ErrorTreeSummary {
+  issueCount: number
+  message: string
+  stackFrames: string[]
+}
+
+function getExpectedErrorStackMessageLines(error: Error): string[] {
+  const [firstMessageLine = '', ...remainingMessageLines] = error.message.split('\n')
+  const headline =
+    error.name === ''
+      ? firstMessageLine
+      : firstMessageLine === ''
+        ? error.name
+        : `${error.name}: ${firstMessageLine}`
+  return [headline, ...remainingMessageLines]
+}
+
+function getStackWithoutMessageDetails(error: Error): string | undefined {
+  const { stack } = error
+  if (stack === undefined) return
+
+  const lines = stack.split('\n')
+  const headline = lines[0]
+  if (headline === undefined) return
+
+  const expectedMessageLines = getExpectedErrorStackMessageLines(error)
+  const hasExpectedMessage = expectedMessageLines.every(
+    (expectedLine, index) => lines[index] === expectedLine,
+  )
+  if (!hasExpectedMessage) return stack
+
+  return [headline, ...lines.slice(expectedMessageLines.length)].join('\n')
+}
+
+function getStackFrameDetails(error: Error): string | undefined {
+  const stack = getStackWithoutMessageDetails(error)
+  if (stack === undefined) return
+
+  const [expectedHeadline] = getExpectedErrorStackMessageLines(error)
+  if (stack === expectedHeadline) return
+  return expectedHeadline !== undefined && stack.startsWith(`${expectedHeadline}\n`)
+    ? stack.slice(expectedHeadline.length + 1)
+    : stack
+}
+
+function summarizeErrorBranch(value: unknown, visited: Set<Error>): ErrorBranchSummary | undefined {
+  if (!(value instanceof Error)) {
+    return { issueCount: 1, messages: [String(value)], stackFrames: [] }
   }
+  if (visited.has(value)) return
+  visited.add(value)
 
-  if (err instanceof Error) {
-    const cause = 'cause' in err ? err.cause : undefined
-    const name = err.name && err.name !== 'Error' ? err.name : ''
-    return [name, err.message, cause == null ? '' : getErrorMessageWithCauses(cause)]
-      .filter(Boolean)
-      .join('\n')
+  const nestedValues =
+    value instanceof AggregateError ? value.errors : value.cause == null ? [] : [value.cause]
+  const nestedSummaries = nestedValues
+    .map((nestedValue) => summarizeErrorBranch(nestedValue, visited))
+    .filter(isPresent)
+  let nestedIssueCount = 0
+  for (const summary of nestedSummaries) {
+    nestedIssueCount += summary.issueCount
+  }
+  const nestedStackFrames = nestedSummaries.flatMap(({ stackFrames }) => stackFrames)
+  const ownMessages =
+    value instanceof AggregateError
+      ? [value.message]
+      : [value.name && value.name !== 'Error' ? value.name : '', value.message]
+  const ownStack = getStackFrameDetails(value)
+
+  return {
+    issueCount: Math.max(1, nestedIssueCount),
+    messages: [...ownMessages, ...nestedSummaries.flatMap(({ messages }) => messages)].filter(
+      (message) => message !== '',
+    ),
+    stackFrames: nestedStackFrames.length > 0 ? nestedStackFrames : [ownStack].filter(isPresent),
+  }
+}
+
+/** Summarize an error graph once, deduplicating shared Error object references by identity. */
+export function summarizeErrorTree(errors: readonly unknown[]): ErrorTreeSummary {
+  const visited = new Set<Error>()
+  const summaries = errors.map((error) => summarizeErrorBranch(error, visited)).filter(isPresent)
+  let issueCount = 0
+  for (const summary of summaries) {
+    issueCount += summary.issueCount
+  }
+
+  return {
+    issueCount,
+    message: summaries.flatMap(({ messages }) => messages).join('\n'),
+    stackFrames: summaries.flatMap(({ stackFrames }) => stackFrames),
   }
+}
 
-  return String(err)
+export function getErrorMessageWithCauses(err: unknown): string {
+  return summarizeErrorTree([err]).message
+}
+
+/** Create one contextual AggregateError from independently collected failures. */
+export function createCollectedError(
+  errors: readonly Error[],
+  context: string,
+  includeDetails = false,
+): AggregateError {
+  const errorTree = summarizeErrorTree(errors)
+  const summary = `${context} found ${errorTree.issueCount} ${errorTree.issueCount === 1 ? 'issue' : 'issues'}`
+  const message = includeDetails ? [summary, errorTree.message].filter(Boolean).join('\n') : summary
+  const aggregateError = new AggregateError(errors, message)
+  if (includeDetails) {
+    aggregateError.stack = [getStackWithoutMessageDetails(aggregateError), ...errorTree.stackFrames]
+      .filter(isPresent)
+      .join('\nCollected error:\n')
+  }
+  return aggregateError
+}
+
+/** Throw a contextual AggregateError when at least one collected failure exists. */
+export function throwCollectedErrors(
+  errors: readonly Error[],
+  context: string,
+  includeDetails = false,
+): void {
+  if (errors.length === 0) return
+
+  throw createCollectedError(errors, context, includeDetails)
 }
 
 export function getErrorCode(err: unknown): unknown {
@@ -43,6 +164,31 @@ export function getNodeErrorCode(err: unknown): string | undefined {
   return typeof code === 'string' ? code : undefined
 }
 
+/** Summarize bounded error names and codes without retaining messages, stacks, or response data. */
+export function summarizeErrorForDiagnostics(error: unknown): string {
+  const pending: unknown[] = [error]
+  const seen = new Set<unknown>()
+  const reasons: string[] = []
+
+  // Error messages, stacks and response objects can contain credentials.
+  for (let index = 0; index < pending.length && index < 8; index += 1) {
+    const current = pending[index]
+    if (!isRecord(current) || seen.has(current)) continue
+    seen.add(current)
+    const name =
+      typeof current.name === 'string' && /^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(current.name)
+        ? current.name
+        : 'Error'
+    const code = getNodeErrorCode(current)
+    const reason = code && /^[A-Z][A-Z0-9_]{0,63}$/.test(code) ? `${name} (${code})` : name
+    if (!reasons.includes(reason)) reasons.push(reason)
+    if (current.cause != null) pending.push(current.cause)
+    if (current instanceof AggregateError) pending.push(...current.errors.slice(0, 8))
+  }
+
+  return (reasons.join(' → ') || 'UnknownError').slice(0, 220)
+}
+
 export function isErrnoException(err: unknown): err is NodeJS.ErrnoException {
   return isRecord(err) && 'code' in err
 }

package/src/alphalib/imagemagickDensity.ts

@@ -1,7 +1,8 @@
-const positiveDecimalDensityPart = String.raw`(?:0*[1-9]\d*(?:\.\d+)?|0+\.\d*[1-9]\d*)`
+const positiveDecimalDensityPart = String.raw`(?:0*[1-9][0-9]*(?:\.[0-9]+)?|0+\.[0-9]*[1-9][0-9]*)`
 
 const imagemagickDensityPattern = new RegExp(
   `^${positiveDecimalDensityPart}(?:x${positiveDecimalDensityPart})?$`,
+  'u',
 )
 
 function isValidImagemagickDensity(value: unknown): boolean {

package/src/alphalib/lib/zodInputSemantics.ts

@@ -0,0 +1,114 @@
+import type { z } from 'zod'
+
+export interface ZodCodePointLengthOptions {
+  readonly max?: number
+  readonly min?: number
+}
+
+/** ECMAScript whitespace for the runtime regular expressions in shared Robot schemas. */
+export const ecmaWhitespaceCharacterClass = String.raw`[\s]`
+
+/** Apply the Robot's output transform using the public Zod API. */
+export function zodInputPreservingTransform<Schema extends z.ZodTypeAny, Output>(
+  schema: Schema,
+  transform: (value: z.output<Schema>) => Output,
+) {
+  // Inference retains each Zod version's native effect/pipe type for generated schema consumers.
+  return schema.transform(transform)
+}
+
+/** JSON input projections belong to API2's publisher; the SDK validates with the original schema. */
+export function zodWithJsonInputSchema<Schema extends z.ZodTypeAny>(
+  schema: Schema,
+  _jsonInputSchema: z.ZodTypeAny,
+): Schema {
+  return schema
+}
+
+/** Conservative publication annotations likewise leave runtime validation and transforms intact. */
+export function zodWithConservativeJsonInputSchema<Schema extends z.ZodTypeAny>(
+  schema: Schema,
+  _jsonInputSchema: z.ZodTypeAny,
+): Schema {
+  return schema
+}
+
+function isStableJsonValue(value: unknown, ancestors = new Set<object>()): boolean {
+  if (value === null || typeof value === 'boolean' || typeof value === 'string') return true
+  if (typeof value === 'number') return Number.isFinite(value)
+  if (typeof value !== 'object' || ancestors.has(value)) return false
+
+  ancestors.add(value)
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index += 1) {
+      if (!Object.hasOwn(value, index) || !isStableJsonValue(value[index], ancestors)) return false
+    }
+    ancestors.delete(value)
+    return true
+  }
+
+  const stable =
+    (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null) &&
+    Object.values(value).every((entry) => isStableJsonValue(entry, ancestors))
+  ancestors.delete(value)
+  return stable
+}
+
+/** Snapshot a JSON default and parse a fresh copy for each omitted input. */
+export function zodStableJsonDefault<Schema extends z.ZodTypeAny>(
+  schema: Schema,
+  defaultValue: Exclude<z.input<Schema>, undefined>,
+) {
+  if (!isStableJsonValue(defaultValue)) {
+    throw new Error('A stable JSON default must contain only finite JSON values')
+  }
+  if (!schema.safeParse(defaultValue).success) {
+    throw new Error('A stable JSON default must satisfy its schema')
+  }
+
+  const snapshot = structuredClone(defaultValue)
+  // The Zod 4 generator must use prefault here so defaults still run validation and transforms.
+  return schema.default(() => structuredClone(snapshot))
+}
+
+function assertLengthBoundary(name: 'max' | 'min', value: number | undefined): void {
+  if (value !== undefined && (!Number.isSafeInteger(value) || value < 0)) {
+    throw new Error(`Zod code-point ${name} must be a nonnegative safe integer`)
+  }
+}
+
+/** Validate Unicode code points, so supplementary characters count as one character. */
+export function zodCodePointLength<Schema extends z.ZodString>(
+  schema: Schema,
+  { max, min }: ZodCodePointLengthOptions,
+) {
+  assertLengthBoundary('max', max)
+  assertLengthBoundary('min', min)
+  if (max === undefined && min === undefined) {
+    throw new Error('Zod code-point length requires a minimum or maximum')
+  }
+  if (max !== undefined && min !== undefined && min > max) {
+    throw new Error('Zod code-point minimum cannot exceed its maximum')
+  }
+
+  return schema.superRefine((value, context) => {
+    let length = 0
+    for (const _character of value) {
+      length += 1
+      if (max !== undefined && length > max) {
+        context.addIssue({
+          code: 'custom',
+          message: `Must contain at most ${max} Unicode code points`,
+        })
+        return
+      }
+      if (max === undefined && min !== undefined && length >= min) return
+    }
+    if (min !== undefined && length < min) {
+      context.addIssue({
+        code: 'custom',
+        message: `Must contain at least ${min} Unicode code points`,
+      })
+    }
+  })
+}

package/src/alphalib/object.ts

@@ -1,4 +1,4 @@
-import type { Entries } from 'type-fest'
+import type { ObjectEntries } from './types/utility.ts'
 
 export type UnknownRecord = Record<PropertyKey, unknown>
 
@@ -7,6 +7,34 @@ export type UnknownRecord = Record<PropertyKey, unknown>
  * some background on why this exists and why this isn't in TypeScript by default.
  */
 
+/**
+ * Create a predicate that narrows an object property to a present value.
+ */
+export function hasPresentKey<K extends PropertyKey>(key: K) {
+  return <T, V>(
+    value: T & { [Property in K]?: V | null | undefined },
+  ): value is T & { [Property in K]: V } => value[key] !== undefined && value[key] !== null
+}
+
+/**
+ * Create a predicate that narrows an object property to one exact value.
+ */
+export function hasValueAtKey<K extends PropertyKey, V>(key: K, expectedValue: V) {
+  return <T extends Record<K, unknown>>(value: T): value is T & Record<K, V> =>
+    value[key] === expectedValue
+}
+
+/** Return whether a value is not undefined. */
+export function isDefined<T>(value: T | undefined): value is T {
+  return value !== undefined
+}
+
+/** Return whether a value is neither null nor undefined. */
+// biome-ignore lint/suspicious/noConfusingVoidType: Shared callers filter results from callbacks that may return void.
+export function isPresent<T>(value: T | null | undefined | void): value is T {
+  return value !== undefined && value !== null
+}
+
 export function isRecord(value: unknown): value is UnknownRecord {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
@@ -27,6 +55,94 @@ export function isStringRecord(value: unknown): value is Record<string, string>
   return Object.values(value).every((entry) => typeof entry === 'string')
 }
 
+/**
+ * Return the enumerable entries of a record except for the requested keys.
+ *
+ * This intentionally targets data records rather than preserving prototypes, symbols, or property
+ * descriptors.
+ */
+export function omitRecordKeys(
+  record: object,
+  omittedKeys: readonly PropertyKey[],
+): Record<string, unknown> {
+  const omitted = new Set(omittedKeys)
+  return Object.fromEntries(Object.entries(record).filter(([key]) => !omitted.has(key)))
+}
+
+const unsafeRecordPathSegments = new Set(['__proto__', 'constructor', 'prototype'])
+
+/**
+ * Set a dot-delimited path on a data record, creating missing record segments along the way.
+ */
+export function setRecordPath(record: object, path: string, value: unknown): void {
+  const segments = path.split('.')
+  if (segments.some((segment) => segment === '')) {
+    throw new Error(`Invalid record path: ${path}`)
+  }
+  if (segments.some((segment) => unsafeRecordPathSegments.has(segment))) {
+    throw new Error(`Unsafe record path: ${path}`)
+  }
+
+  if (!isRecord(record)) {
+    throw new Error('Expected a data record')
+  }
+
+  let current = record
+  for (const [index, segment] of segments.entries()) {
+    if (index === segments.length - 1) {
+      current[segment] = value
+      return
+    }
+
+    const child = current[segment]
+    if (isRecord(child)) {
+      current = child
+      continue
+    }
+
+    const newChild: UnknownRecord = {}
+    current[segment] = newChild
+    current = newChild
+  }
+}
+
+function isFlattenable(value: unknown): value is object {
+  return (
+    Array.isArray(value) ||
+    (typeof value === 'object' &&
+      value !== null &&
+      Object.prototype.toString.call(value) === '[object Object]')
+  )
+}
+
+/**
+ * Flatten nested objects and arrays into delimiter-separated keys.
+ *
+ * Empty containers and non-plain objects remain leaf values.
+ */
+export function flattenObject(value: object, delimiter = '.'): Record<string, unknown> {
+  const flattened: Record<string, unknown> = {}
+
+  function visit(currentValue: unknown, keyPath: string): void {
+    const childEntries = isFlattenable(currentValue) ? Object.entries(currentValue) : []
+
+    if (childEntries.length === 0) {
+      flattened[keyPath] = currentValue
+      return
+    }
+
+    for (const [key, childValue] of childEntries) {
+      visit(childValue, keyPath ? `${keyPath}${delimiter}${key}` : key)
+    }
+  }
+
+  for (const [key, childValue] of Object.entries(value)) {
+    visit(childValue, key)
+  }
+
+  return flattened
+}
+
 export function getRecordProperty(value: unknown, property: PropertyKey): unknown {
   if (!isRecord(value)) {
     return undefined
@@ -35,6 +151,17 @@ export function getRecordProperty(value: unknown, property: PropertyKey): unknow
   return value[property]
 }
 
+/** Read a nested property from own data-record keys without traversing arrays or prototypes. */
+export function getPropertyByPath(value: unknown, properties: readonly PropertyKey[]): unknown {
+  let result = value
+  for (const property of properties) {
+    if (!isRecord(result) || !Object.hasOwn(result, property)) return undefined
+    result = result[property]
+  }
+
+  return result
+}
+
 export function getNestedRecordProperty(
   value: unknown,
   first: PropertyKey,
@@ -74,8 +201,9 @@ export function getNestedNumberProperty(
 /**
  * Returns properly typed entries of an object
  */
-export function entries<T extends { [K in keyof T]: T[K] }>(object: T): Entries<T> {
-  return Object.entries(object) as Entries<T>
+export function entries<T extends { [K in keyof T]: T[K] }>(object: T): ObjectEntries<T> {
+  // Object.entries loses the relationship between T's keys and values in the standard library.
+  return Object.entries(object) as ObjectEntries<T>
 }
 
 /**
@@ -91,3 +219,50 @@ export function values<T extends object>(object: T): T[keyof T][] {
 export function keys<T extends object>(object: T): (keyof T)[] {
   return Object.keys(object) as (keyof T)[]
 }
+
+type SortPriorities = Record<string, (RegExp | string)[]>
+
+/** Return a shallow object copy with its string keys sorted. */
+export function sortObject<T extends Record<string, unknown>>(
+  object: T,
+  compare?: (firstKey: string, secondKey: string) => number,
+): T {
+  const sortedEntries = Object.keys(object)
+    .sort(compare)
+    .map((key) => [key, object[key]])
+
+  // Object.fromEntries cannot express that reordering entries preserves T's keys and values.
+  return Object.fromEntries(sortedEntries) as T
+}
+
+/**
+ * Sort object keys alphabetically while pulling `_` matches forward and pushing other prefixes
+ * backward in their configured order.
+ */
+export function sortObjectByPrio<T extends Record<string, unknown>>(
+  object: T,
+  priorities: SortPriorities,
+): T {
+  return sortObject(object, (firstKey, secondKey) => {
+    let firstSortableKey = firstKey
+    let secondSortableKey = secondKey
+
+    for (const [prefix, matchers] of Object.entries(priorities)) {
+      for (const [index, matcher] of matchers.entries()) {
+        const modifier = prefix === '_' ? matchers.length - index : index
+        const sortablePrefix = prefix.repeat(2 + modifier)
+        const matches = (key: string): boolean =>
+          matcher instanceof RegExp ? matcher.test(key) : key === matcher
+
+        if (matches(firstSortableKey)) {
+          firstSortableKey = `${sortablePrefix}${firstSortableKey}`
+        }
+        if (matches(secondSortableKey)) {
+          secondSortableKey = `${sortablePrefix}${secondSortableKey}`
+        }
+      }
+    }
+
+    return firstSortableKey.localeCompare(secondSortableKey)
+  })
+}

package/src/alphalib/stepParsing.ts

@@ -529,13 +529,19 @@ export const parseSafeTemplate = (
   return [null, safe, indent]
 }
 
-export function botNeedsInput(robotName: string, stepName?: string, step?: StepInput) {
+/** Whether the Robot requires input, independent of any declared Step dependencies. */
+export function botNeedsInput(robotName: string, stepName?: string, step?: StepInput): boolean {
   if (robotName.endsWith('/import')) {
     return false
   }
   if (robotName === '/upload/handle') {
     return false
   }
+  if (robotName === '/http/request') {
+    // Match HttpRequestRobot's no-input mode; interpolated payloads remain conservative.
+    const payload = step && 'payload' in step ? step.payload : undefined
+    return !(payload == null || payload === 'none' || payload === 'metadata')
+  }
   if (robotName === '/html/convert') {
     if (step && 'url' in step && typeof step.url === 'string' && step.url) {
       return false
@@ -596,6 +602,8 @@ const getFirstStepNameThatDoesNotNeedInputFromSteps = (
         step !== null &&
         typeof step.robot === 'string' &&
         !botNeedsInput(step.robot, stepName, step) &&
+        // Reuse the SDK's use parser: optional input does not make a dependent Step a root.
+        getLastUsedStepName(step) === undefined &&
         !excludeBots.includes(step.robot)
       )
     }) ?? ''
@@ -821,7 +829,7 @@ export function addFilePreviewRobot(templateContent: string): string {
 
   // Identify steps and extract width
   for (const [stepName, step] of entries(steps)) {
-    if (!botNeedsInput(step.robot)) {
+    if (!botNeedsInput(step.robot, stepName, step)) {
       importStepName = stepName
     } else if (['/image/resize', '/video/thumb'].includes(step.robot)) {
       if ('width' in step && (typeof step.width === 'number' || typeof step.width === 'string')) {

package/src/alphalib/types/apiParameterDescription.ts

@@ -0,0 +1,41 @@
+import type { z } from 'zod'
+
+/** Portable copy paired with the publisher's richer glossary rendering. */
+export interface ApiParameterDescriptionSource {
+  readonly commonMark: string
+  readonly referenceMarkdown: string
+}
+
+export type ApiParameterDescription = string | ApiParameterDescriptionSource
+
+/** Keep useful parameter help without importing API2's translation identity registry. */
+export function describeApiParameter<Schema extends z.ZodTypeAny>(
+  _descriptionId: string,
+  schema: Schema,
+  description: ApiParameterDescription,
+): Schema {
+  return schema.describe(typeof description === 'string' ? description : description.commonMark)
+}
+
+/** Preserve portable help when rebuilding a schema, without publication-only metadata. */
+export function inheritApiParameterDescription<Schema extends z.ZodTypeAny>(
+  source: z.ZodTypeAny,
+  target: Schema,
+): Schema {
+  return source.description === undefined ? target : target.describe(source.description)
+}
+
+/** Attach available field help while retaining the original shape's types and runtime behavior. */
+export function describeApiParameterFields<Shape extends Record<string, z.ZodTypeAny>>(
+  scope: string,
+  shape: Shape,
+  descriptions: Readonly<Partial<Record<string, ApiParameterDescription>>>,
+): Shape {
+  const describedShape = { ...shape }
+  for (const field in describedShape) {
+    const description = Object.hasOwn(descriptions, field) ? descriptions[field] : undefined
+    if (description === undefined) continue
+    describedShape[field] = describeApiParameter(scope, describedShape[field], description)
+  }
+  return describedShape
+}