/**
 * @module
 *
 * the error taxonomy thrown by {@link zip} and {@link unzip}. every error is
 * an instance of {@link ZipError}, so a caller can branch with `instanceof`
 * for the cases it knows how to recover from (re-prompt on
 * {@link InvalidPasswordError}, prompt for one on {@link MissingPasswordError})
 * and fall through to a generic `ZipError` for the rest.
 */

/** base class for every error thrown by the zip library. */
export class ZipError extends Error {
	override name: string = 'ZipError';
}

/**
 * an extracted entry's data did not match the checksum or size recorded in
 * the archive — covers the central directory CRC32 and declared size checks.
 */
export class ChecksumMismatchError extends ZipError {
	override name: string = 'ChecksumMismatchError';
}

/**
 * a password was supplied but does not match the archive's stored check
 * value. the caller can re-prompt and retry with a different password.
 */
export class InvalidPasswordError extends ZipError {
	override name: string = 'InvalidPasswordError';
}

/** the source bytes do not begin with a recognized zip signature. */
export class InvalidSignatureError extends ZipError {
	override name: string = 'InvalidSignatureError';
}

/**
 * the archive's structure is corrupt or violates the format spec: a header
 * field is out of range, a central record runs past its directory bounds,
 * an EOCD cannot be located, etc. there is nothing the caller can recover
 * by retrying.
 */
export class MalformedArchiveError extends ZipError {
	override name: string = 'MalformedArchiveError';
}

/**
 * the archive (or one of its entries) is encrypted but no password was
 * supplied. the caller can prompt the user and retry with a password.
 */
export class MissingPasswordError extends ZipError {
	override name: string = 'MissingPasswordError';
}

/**
 * a multi-volume archive's set of volume readers is incomplete — the EOCD
 * (or an entry's disk-number field) references a disk index past the end of
 * the supplied readers, or only the terminating volume was passed in. the
 * caller can ask for the missing volumes and retry.
 */
export class MissingVolumeError extends ZipError {
	override name: string = 'MissingVolumeError';
}

/**
 * the underlying {@link Reader} failed to deliver bytes — an HTTP fetch
 * returned a non-2xx status, a content-length header was missing, a server
 * did not honour a range request, and so on. distinct from
 * {@link TruncatedArchiveError}, which fires when the reader succeeds but
 * the archive itself ends mid-structure.
 */
export class ReaderError extends ZipError {
	override name: string = 'ReaderError';
}

/**
 * the archive ends in the middle of a structure: a record declares more
 * bytes than the source contains, a stream runs out before the expected
 * number of bytes is delivered, or the source is shorter than the minimum
 * zip framing.
 */
export class TruncatedArchiveError extends ZipError {
	override name: string = 'TruncatedArchiveError';
}

/**
 * the archive uses a feature this library does not implement yet — an
 * unsupported compression method, an unrecognized encryption scheme, and
 * so on.
 */
export class UnsupportedFeatureError extends ZipError {
	override name: string = 'UnsupportedFeatureError';
}