Library API

Embed chop in your own server with createHandler, and look up its exports and error codes.

Open as Markdown

Call chop from your own code: pass a request object to the handler and get a response object back, with no HTTP framework in between. That runs in a node:http server, a serverless function or a test. Install the package as described in the overview.

import { createHandler, createServer } from '@wpelevator/chop';

const handle = createHandler( {
	dataDir: '/var/www/uploads',
	onError: ( error ) => console.error( error ),
} );

const response = await handle( {
	method: 'GET',
	url: '/2026/05/photo.jpg?w=800',
	headers: { accept: 'image/avif,image/webp' },
} );
// { status: 200, headers: { 'content-type': 'image/avif', ... }, body: Buffer }

createServer( { dataDir: '/var/www/uploads' } ).listen( 8080 );

Reference

Exports

Export Description
createHandler( settings? ) Returns ( request ) => Promise< Response >. The request is { method, url, headers }, where url is the path and query string and headers is a plain object with lower-case names. The response is { status, headers, body } with a Buffer body. It doesn't depend on node:http, never throws for a request (errors become responses) and takes optional callbacks, because the library never logs: onError( error ) for unexpected errors, onWarning( message ) for each risky setting (like allowedHosts: [ '*' ]) when the handler is created, and onOriginError( error ) for a refused or failed origin, where error.detail says why and has no credentials. Pass the settings that you want to change, such as { origin: 'https://uploads.example.com' }. Don't pass the result of createConfig() together with an origin, because createConfig() fills in the default dataDir, and a data directory together with an origin is an invalid setting.
createConfig( overrides? ), configWarnings( settings ) Settings with defaults, checked, and the list of warnings for the risky settings in them. Throws a ChopError with ERR_INVALID_SETTING for a value that can't be used.
configFromEnv( env ) The settings that the CHOP_* variables in an environment object set. It doesn't read process.
parseQuery( searchParams ) Parses a URLSearchParams into typed operations.
queryScheme, cloudflareScheme, SCHEMES, SCHEME_NAMES The built-in URL schemes, the registry of them by name, and the list of names. The UrlScheme type describes a scheme: { name, parse( url, options ) }, where url is a URL object and not a string, and parse returns { segments, ops }, with url set instead of segments for a URL source, or null for a URL that it doesn't recognize. options.urlSources tells whether URL sources are enabled.
createOrigin( settings ), createLocalOrigin(), createHttpOrigin(), createS3Origin() The sources of originals. createOrigin() takes the full settings that createConfig() returns, and partial settings throw a TypeError. The Origin type has open( reference ), which finds an original and returns its size and a read() for its bytes. The HTTP origin does the downloads and their checks.
isBlockedAddress( address ), createBlockList(), parseAllowedHosts(), parseSourceUrl() The building blocks of the safeguards, for code that wants to apply the same checks.
DEFAULT_SETTINGS, INPUT_FORMATS, AUTO_FORMATS The default settings, the readable input formats and the formats that auto can negotiate.
parseAccept( header ), acceptsType( header, type ) Parse an Accept header per RFC 9110, and check that a media type is listed the way chop does. Wildcards don't count.
planGeometry(), estimateJpegQuality(), createLimiter() Lower-level parts of the pipeline: the size plan for a request, the quality estimate of a JPEG, and the queue that limits concurrent work.
createServer( settings? ) A node:http server around the handler, with an onResponse( summary ) callback for access logs.
run( args, io ) The command, which returns an exit code. io has stdout, stderr, env, cwd and signals, all replaceable in tests.
ChopError, isChopError( value ), statusOf( error ), CHOP_ERROR_CODES, CHOP_ERROR_STATUS Errors with a code. isChopError checks the code instead of instanceof, and statusOf returns the HTTP status of any error.

Error codes

Error code HTTP status
ERR_INVALID_REQUEST 400
ERR_NOT_FOUND 404
ERR_METHOD_NOT_ALLOWED 405
ERR_INPUT_TOO_LARGE 413
ERR_UNSUPPORTED_TYPE 415
ERR_UNREADABLE_IMAGE 422
ERR_UPSTREAM 502
ERR_UPSTREAM_TIMEOUT 504
ERR_BUSY 503
ERR_INVALID_SETTING 500 (reported by the CLI at startup, exit code 2)
ERR_INTERNAL 500