Postconditions: what we check

• extract · extract-error-handling

  error
  Whenasync call to tar.extract() or extract() with a file: option is awaited without a try-catch block. Rejects with Error where error.code is one of: TAR_BAD_ARCHIVE, TAR_ENTRY_ERROR, TAR_ABORT, CwdError, SymlinkError, ENOENT, EACCES, or ENOSPC.
  ThrowsError (code: TAR_BAD_ARCHIVE | TAR_ENTRY_ERROR | TAR_ABORT | CwdError | SymlinkError | ENOENT | EACCES | ENOSPC)
  Required handlingCaller MUST wrap tar.extract() in try-catch and handle extraction errors. Minimum handling: try { await tar.extract({ file: archivePath, cwd: targetDir }); } catch (error) { console.error('Extraction failed:', error.message, error.code); throw error; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• x · extract-error-handling

  error
  Whenasync call to tar.x() with a file: option is awaited without a try-catch block. Rejects with Error where error.code is one of: TAR_BAD_ARCHIVE, TAR_ENTRY_ERROR, TAR_ABORT, CwdError, SymlinkError, ENOENT, EACCES, ENOSPC.
  ThrowsError (code: TAR_BAD_ARCHIVE | TAR_ENTRY_ERROR | TAR_ABORT | CwdError | SymlinkError | ENOENT | EACCES | ENOSPC)
  Required handlingCaller MUST wrap tar.x() in try-catch and handle extraction errors. Minimum handling: try { await tar.x({ file: archivePath, cwd: targetDir }); } catch (error) { console.error('Extraction failed:', error.message, error.code); throw error; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• create · create-error-handling

  error
  Whenasync call to tar.create() or create() with a file: option is awaited without a try-catch block. Rejects with filesystem errors (ENOENT, EACCES, ENOSPC), CwdError, or TAR_ENTRY_ERROR.
  ThrowsError (code: TAR_ENTRY_ERROR | CwdError | ENOENT | EACCES | ENOSPC)
  Required handlingCaller MUST wrap tar.create() in try-catch and handle creation errors. Minimum handling: try { await tar.create({ file: outputPath, gzip: true }, files); } catch (error) { console.error('Archive creation failed:', error.message, error.code); throw error; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• c · create-error-handling

  error
  Whenasync call to tar.c() with a file: option is awaited without a try-catch block. Rejects with filesystem errors (ENOENT, EACCES, ENOSPC), CwdError, or TAR_ENTRY_ERROR.
  ThrowsError (code: TAR_ENTRY_ERROR | CwdError | ENOENT | EACCES | ENOSPC)
  Required handlingCaller MUST wrap tar.c() in try-catch and handle creation errors. Minimum handling: try { await tar.c({ file: outputPath }, files); } catch (error) { console.error('Archive creation failed:', error.message, error.code); throw error; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• list · list-error-handling

  error
  Whenasync call to tar.list() with a file: option is awaited without a try-catch block. The Promise rejects when: the archive file does not exist (ENOENT), a permission error prevents reading (EACCES), the archive is corrupt (TAR_BAD_ARCHIVE emitted by Parser), or gzip/brotli decompression fails (TAR_ABORT). These are unrecoverable errors per tar's "Warnings and Errors" classification.
  ThrowsError (code: ENOENT | EACCES | TAR_BAD_ARCHIVE | TAR_ABORT)
  Required handlingCaller MUST wrap tar.list() in try-catch when using the file: option. Minimum handling: try { const entries: string[] = []; await tar.list({ file: archivePath, onReadEntry: entry => entries.push(entry.path), }); return entries; } catch (error) { console.error('Failed to list archive:', error.message, error.code); throw error; }
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• t · list-error-handling

  error
  Whenasync call to tar.t() with a file: option is awaited without a try-catch block. Rejects with ENOENT (missing file), EACCES (permission error), TAR_BAD_ARCHIVE (corrupt archive), or TAR_ABORT (decompression failure).
  ThrowsError (code: ENOENT | EACCES | TAR_BAD_ARCHIVE | TAR_ABORT)
  Required handlingCaller MUST wrap tar.t() in try-catch when using the file: option. Minimum handling: try { await tar.t({ file: archivePath, onReadEntry: entry => process(entry) }); } catch (error) { console.error('Failed to list archive:', error.message, error.code); throw error; }
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• replace · replace-compressed-archive-error

  error
  WhenCall to tar.replace() or tar.r() where gzip: true, brotli: true, or zstd: true options are set, or where the file path ends with .gz, .tgz, .br, .tbr, .zst, .tzst. The validate function throws TypeError synchronously before any I/O: "cannot append to compressed archives". This throws before any Promise is created, so try-catch (not .catch()) must be used.
  ThrowsTypeError('cannot append to compressed archives')
  Required handlingNever call tar.replace() on compressed archives (.tgz, .tar.gz, .tar.br, .tar.zst). Decompress first, then work with the uncompressed .tar, then recompress if needed. If the compression state is unknown at call time, wrap in try-catch: try { await tar.replace({ file: archivePath }, newFiles); } catch (error) { if (error instanceof TypeError && error.message.includes('compressed')) { throw new Error('Cannot modify compressed archive: decompress first'); } throw error; }
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• replace · replace-error-handling

  error
  Whenasync call to tar.replace() with a file: option is awaited without a try-catch block. Can reject with filesystem errors (EACCES if archive file cannot be opened for writing), or errors from the Pack stream writing to the archive.
  ThrowsError (code: EACCES | ENOENT | TAR_ENTRY_ERROR)
  Required handlingCaller MUST wrap tar.replace() in try-catch to handle I/O errors. Minimum handling: try { await tar.replace({ file: archivePath }, ['newfile.txt']); } catch (error) { console.error('Failed to update archive:', error.message, error.code); throw error; }
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• r · replace-compressed-archive-error

  error
  WhenCall to tar.r() where gzip/brotli/zstd options are set or file is compressed. Throws TypeError synchronously.
  ThrowsTypeError('cannot append to compressed archives')
  Required handlingNever call tar.r() on compressed archives. If compression state is unknown, use try-catch.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• r · replace-error-handling

  error
  Whenasync call to tar.r() with a file: option is awaited without a try-catch block. Rejects with filesystem errors (EACCES, ENOENT on open), or Pack stream errors.
  ThrowsError (code: EACCES | ENOENT | TAR_ENTRY_ERROR)
  Required handlingWrap tar.r() in try-catch to handle I/O errors.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• update · update-compressed-archive-error

  error
  WhenCall to tar.update() or tar.u() where gzip: true, brotli: true, or zstd: true options are set, or where the file ends with a compressed extension. Throws TypeError synchronously (same as tar.replace).
  ThrowsTypeError('cannot append to compressed archives')
  Required handlingNever call tar.update() on compressed archives. Use uncompressed .tar files for archives that need incremental updates. If compression state is unknown, use try-catch.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• update · update-error-handling

  error
  Whenasync call to tar.update() with a file: option is awaited without a try-catch block. Rejects with filesystem errors (EACCES if archive cannot be opened, ENOENT on fs operations), or errors from the underlying Pack stream.
  ThrowsError (code: EACCES | ENOENT | TAR_ENTRY_ERROR)
  Required handlingCaller MUST wrap tar.update() in try-catch to handle I/O errors. Minimum handling: try { await tar.update({ file: archivePath }, ['updatedfile.txt']); } catch (error) { console.error('Failed to update archive:', error.message, error.code); throw error; }
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• u · update-compressed-archive-error

  error
  WhenCall to tar.u() where gzip/brotli/zstd options are set or file is compressed. Throws TypeError synchronously.
  ThrowsTypeError('cannot append to compressed archives')
  Required handlingNever call tar.u() on compressed archives. Use try-catch if compression state is unknown.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• u · update-error-handling

  error
  Whenasync call to tar.u() with a file: option is awaited without a try-catch block. Rejects with filesystem errors (EACCES, ENOENT), or Pack stream errors.
  ThrowsError (code: EACCES | ENOENT | TAR_ENTRY_ERROR)
  Required handlingWrap tar.u() in try-catch to handle I/O errors.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.