@eazip/core

Reference for Core functions, ZIP options, jobs, results, errors, and package entry points.

npm install @eazip/core

Primary functions

Function	Returns	Use it when
`createZip(options)`	`Promise<ZipResult>`	You only need the finished output.
`startZip(options)`	`ZipJob`	You need progress, cancellation, or observable state.

Both use Local execution unless strategy: 'cloud' is present.

`createZip(options)`

import { createZip } from '@eazip/core';

const result = await createZip({
  files,
  zipName: 'export.zip',
});

result.download();

The promise resolves for completed and partial output. It rejects for validation, cancellation, and fatal failures.

Shared options

Option	Type	Default	Description
`files`	`ZipInput`	required for source-created jobs	Files, blobs, URLs, or source objects.
`zipName`	`string`	`'download.zip'`	Output name; `.zip` is added when omitted.
`strategy`	`'local' \| 'cloud'`	`'local'`	Execution location.
`failOnUrlError`	`boolean`	`false`	Fail instead of keeping usable output.
`maxZipSizeBytes`	`number`	—	Best-effort output part size.
`signal`	`AbortSignal`	—	Cancels Local work or stops Cloud polling.
`fetch`	`FetchLike`	global `fetch`	Custom source and Cloud requests.
`onChange`	`(snapshot) => void`	—	Called after job snapshot changes.

Local options

Option	Type	Default	Description
`compressionLevel`	integer `0`–`9`	`6`	Deflate compression level.
`concurrency`	`number`	`4`	Maximum parallel URL fetches.
`onProgress`	`(progress) => void`	—	Local file and byte progress.

Frontend-created Cloud options

Option	Type	Default	Description
`strategy`	`'cloud'`	required	Selects Cloud execution.
`publicKey`	`string`	required	Browser-safe `pk_ez_...` key.
`files`	`ZipInput`	required	URL sources; File and Blob values fail validation.
`apiBaseUrl`	`string`	SDK Cloud endpoint	Overrides the Cloud API origin.
`mode`	`'stream' \| 'stored'`	`'stream'`	Cloud delivery mode.
`turnstileToken`	`string`	—	Pre-obtained challenge token.
`onChallenge`	`(challenge) => Promise<string>`	—	Resolves a requested challenge once.
`polling`	`PollingOptions`	SDK defaults	Overrides Cloud polling behavior.

For backend-created Cloud jobs, pass createSession(context) instead of files and publicKey. filesTotal can provide an initial UI count.

Results

Both strategies expose:

Member	Description
`strategy`	`'local'` or `'cloud'`.
`status`	`'completed'` or `'partial'`.
`zips`	One entry per output ZIP.
`errors`	Per-file Local errors; currently empty for Cloud output.
`skippedCount`	Number of omitted sources.
`download(index?)`	Downloads one ZIP, defaulting to index `0`.
`downloadAll()`	Downloads every output ZIP.

Local results also expose totalSize and dispose(). Cloud results expose sessionId, clientSecret, expiresAt, and session.

`startZip(options)`

import { startZip } from '@eazip/core';

const job = startZip({ files });
const unsubscribe = job.subscribe(() => {
  console.log(job.getSnapshot().status);
});

try {
  const result = await job.done;
  result.download();
} finally {
  unsubscribe();
}

startZip() accepts the same option shapes as createZip().

Job members

Member	Description
`id`	Stable job identifier.
`strategy`	Fixed Local or Cloud strategy.
`getSnapshot()`	Returns the current immutable snapshot.
`subscribe(listener)`	Subscribes to changes and returns an unsubscribe function.
`done`	Resolves with usable output or rejects with the terminal error.
`abort()`	Stops Local work or Cloud polling.
`download(index?)`	Downloads one ready output.
`downloadAll()`	Downloads every ready output.
`dispose()`	Releases Local object URLs; a no-op for Cloud.

Snapshot fields

Field	Description
`jobId` / `strategy`	Job identity and execution strategy.
`status`	`starting`, `processing`, `completed`, `partial`, `failed`, or `aborted`.
`progress`	Local progress; `null` for Cloud.
`zips`	Output available so far.
`errors` / `skippedCount`	Omitted source information.
`error`	Fatal error for a failed job.
`session`	Cloud session credentials and latest server job.
`result`	Final result after completion or partial completion.

Resume Cloud jobs

import { resumeZip } from '@eazip/core';

const job = resumeZip({
  sessionId,
  clientSecret,
  apiBaseUrl,
});

resumeZip() returns a ZipJob. It reconnects to an existing session and does not create a new job.

Errors

All SDK errors extend EazipErrorBase. Use isEazipError() to narrow an unknown value and read its stable code.

Class	Typical condition
`EazipValidationError`	Invalid input, missing key, or API misuse.
`EazipAbortError`	The job or supplied signal was aborted.
`EazipNetworkError`	A browser or Cloud request could not be made.
`EazipApiError`	Cloud API error without a more specific subclass.
`EazipChallengeRequiredError`	Cloud requires an anti-abuse challenge.
`EazipRateLimitError`	Cloud rate limit; may include `retryAfterMs`.
`EazipQuotaError`	Cloud plan or quota limit.
`EazipJobFailedError`	The server-side ZIP job failed.
`EazipSessionExpiredError` / `EazipSessionRevokedError`	Session credentials are no longer usable.
`EazipDownloadExpiredError`	A Cloud output link is no longer usable.

Package entry points

Import	Notable exports
`@eazip/core`	Recommended functions, shared types, and errors.
`@eazip/core/local`	`createLocalZip`, `startLocalZip`, and filename utilities.
`@eazip/core/cloud`	`startCloudZip`, `resumeZip`, `SessionsClient`, and `DEFAULT_API_BASE_URL`.
`@eazip/core/shared`	Shared types, errors, input normalization, download, and abort helpers.

Use specialized entry points only when bundle boundaries or lower-level Cloud session access require them.

@eazip/core

On this page