styled-map-package 1.0.1 → 1.1.0

package/bin/smp-view.js

@@ -47,6 +47,7 @@ function serve({ port = 3000, filepath }) {
 
   server.register(smpServer, {
     filepath: path.relative(process.cwd(), filepath),
+    prefix: '/map',
   })
   return server.listen({ port })
 }

package/dist/download.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @typedef {object} DownloadProgress
+ * @property {import('./tile-downloader.js').TileDownloadStats & { done: boolean }} tiles
+ * @property {{ done: boolean }} style
+ * @property {{ downloaded: number, done: boolean }} sprites
+ * @property {import('./style-downloader.js').GlyphDownloadStats & { done: boolean }} glyphs
+ * @property {{ totalBytes: number, done: boolean }} output
+ * @property {number} elapsedMs
+ */
+/**
+ * Download a map style and its resources for a given bounding box and max zoom
+ * level. Returns a readable stream of a "styled map package", a zip file
+ * containing all the resources needed to serve the style offline.
+ *
+ * @param {object} opts
+ * @param {import("./utils/geo.js").BBox} opts.bbox Bounding box to download tiles for
+ * @param {number} opts.maxzoom Max zoom level to download tiles for
+ * @param {string} opts.styleUrl URL of the style to download
+ * @param { (progress: DownloadProgress) => void } [opts.onprogress] Optional callback for reporting progress
+ * @param {string} [opts.accessToken]
+ * @returns {import('./types.js').DownloadStream} Readable stream of the output styled map file
+ */
+export default function download({ bbox, maxzoom, styleUrl, onprogress, accessToken, }: {
+    bbox: import("./utils/geo.js").BBox;
+    maxzoom: number;
+    styleUrl: string;
+    onprogress?: ((progress: DownloadProgress) => void) | undefined;
+    accessToken?: string | undefined;
+}): import("./types.js").DownloadStream;
+export type DownloadProgress = {
+    tiles: import("./tile-downloader.js").TileDownloadStats & {
+        done: boolean;
+    };
+    style: {
+        done: boolean;
+    };
+    sprites: {
+        downloaded: number;
+        done: boolean;
+    };
+    glyphs: import("./style-downloader.js").GlyphDownloadStats & {
+        done: boolean;
+    };
+    output: {
+        totalBytes: number;
+        done: boolean;
+    };
+    elapsedMs: number;
+};

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { default as Reader } from "./reader.js";
+export { default as Writer } from "./writer.js";
+export { default as Server } from "./server.js";
+export { default as StyleDownloader } from "./style-downloader.js";
+export { downloadTiles } from "./tile-downloader.js";
+export { default as download } from "./download.js";
+export type SMPSource = import("./types.js").SMPSource;
+export type SMPStyle = import("./types.js").SMPStyle;

package/dist/reader.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @typedef {object} Resource
+ * @property {string} resourceType
+ * @property {string} contentType
+ * @property {number} contentLength
+ * @property {import('stream').Readable} stream
+ * @property {'gzip'} [contentEncoding]
+ */
+/**
+ * A low-level reader for styled map packages. Returns resources in the package
+ * as readable streams, for serving over HTTP for example.
+ */
+export default class Reader {
+    /**
+     * @param {string | import('yauzl-promise').ZipFile} filepathOrZip Path to styled map package (`.styledmap`) file, or an instance of yauzl ZipFile
+     */
+    constructor(filepathOrZip: string | import("yauzl-promise").ZipFile);
+    /**
+     * Resolves when the styled map package has been opened and the entries have
+     * been read. Throws any error that occurred during opening.
+     */
+    opened(): Promise<void>;
+    /**
+     * Get the style JSON from the styled map package. The URLs in the style JSON
+     * will be transformed to use the provided base URL.
+     *
+     * @param {string | null} [baseUrl] Base URL where you plan to serve the resources in this styled map package, e.g. `http://localhost:3000/maps/styleA`
+     * @returns {Promise<import('./types.js').SMPStyle>}
+     */
+    getStyle(baseUrl?: string | null | undefined): Promise<import("./types.js").SMPStyle>;
+    /**
+     * Get a resource from the styled map package. The path should be relative to
+     * the root of the package.
+     *
+     * @param {string} path
+     * @returns {Promise<Resource>}
+     */
+    getResource(path: string): Promise<Resource>;
+    /**
+     * Close the styled map package file (should be called after reading the file to avoid memory leaks)
+     */
+    close(): Promise<void>;
+    #private;
+}
+export type Resource = {
+    resourceType: string;
+    contentType: string;
+    contentLength: number;
+    stream: import("stream").Readable;
+    contentEncoding?: "gzip" | undefined;
+};

package/dist/reporters.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A writable stream to reporting download progress to a TTY terminal. Write
+ * progress messages to this stream for a pretty-printed progress task-list in
+ * the terminal.
+ */
+export function ttyReporter(): Writable;
+import { Writable } from 'readable-stream';

package/dist/server.d.ts

@@ -0,0 +1,12 @@
+export default function _default(instance: import("fastify").FastifyInstance<import("fastify").RawServerDefault, import("http").IncomingMessage, import("http").ServerResponse<import("http").IncomingMessage>, import("fastify").FastifyBaseLogger, import("fastify").FastifyTypeProviderDefault>, opts: PluginOptions, done: (err?: Error) => void): void;
+export type PluginOptions = {
+    lazy?: boolean | undefined;
+    prefix?: string | undefined;
+    /**
+     * Path to styled map package (`.smp`) file
+     */
+    /**
+     * Path to styled map package (`.smp`) file
+     */
+    filepath: string;
+};

package/dist/style-downloader.d.ts

@@ -0,0 +1,110 @@
+/** @import { SourceSpecification, StyleSpecification } from '@maplibre/maplibre-gl-style-spec' */
+/** @import { TileInfo, GlyphInfo, GlyphRange } from './writer.js' */
+/** @import { TileDownloadStats } from './tile-downloader.js' */
+/** @import { StyleInlinedSources, InlinedSource } from './types.js'*/
+/** @typedef { import('ky').ResponsePromise & { body: ReadableStream<Uint8Array> } } ResponsePromise */
+/** @import { DownloadResponse } from './utils/fetch.js' */
+/**
+ * @typedef {object} GlyphDownloadStats
+ * @property {number} total
+ * @property {number} downloaded
+ * @property {number} totalBytes
+ */
+/**
+ * Download a style and its resources for offline use. Please check the terms of
+ * service of the map provider you are using before downloading any resources.
+ */
+export default class StyleDownloader {
+    /**
+     * @param {string | StyleSpecification} style A url to a style JSON file or a style object
+     * @param {object} [opts]
+     * @param {number} [opts.concurrency=8]
+     * @param {string} [opts.mapboxAccessToken] Downloading a style from Mapbox requires an access token
+     */
+    constructor(style: string | StyleSpecification, { concurrency, mapboxAccessToken }?: {
+        concurrency?: number | undefined;
+        mapboxAccessToken?: string | undefined;
+    } | undefined);
+    /**
+     * Number of active downloads.
+     */
+    get active(): number;
+    /**
+     * Download the style JSON for this style and inline the sources
+     *
+     * @returns {Promise<StyleInlinedSources>}
+     */
+    getStyle(): Promise<StyleInlinedSources>;
+    /**
+     * Download the sprite PNGs and JSON files for this style. Returns an async
+     * generator of json and png readable streams, and the sprite id and pixel
+     * ratio. Downloads pixel ratios `1` and `2`.
+     *
+     * @returns {AsyncGenerator<{ json: import('stream').Readable, png: import('stream').Readable, id: string, pixelRatio: number }>}
+     */
+    getSprites(): AsyncGenerator<{
+        json: import("stream").Readable;
+        png: import("stream").Readable;
+        id: string;
+        pixelRatio: number;
+    }>;
+    /**
+     * Download all the glyphs for the fonts used in this style. When font stacks
+     * are used in the style.json (e.g. lists of prefered fonts like with CSS),
+     * then the first font in the stack is downloaded. Defaults to downloading all
+     * UTF character ranges, which may be overkill for some styles. TODO: add more
+     * options here.
+     *
+     * Returns an async generator of readable streams of glyph data and glyph info
+     * objects.
+     *
+     * @param {object} opts
+     * @param {(progress: GlyphDownloadStats) => void} [opts.onprogress]
+     * @returns {AsyncGenerator<[import('stream').Readable, GlyphInfo]>}
+     */
+    getGlyphs({ onprogress }?: {
+        onprogress?: ((progress: GlyphDownloadStats) => void) | undefined;
+    }): AsyncGenerator<[import("stream").Readable, GlyphInfo]>;
+    /**
+     * Get all the tiles for this style within the given bounds and zoom range.
+     * Returns an async generator of readable streams of tile data and tile info
+     * objects.
+     *
+     * The returned iterator also has a `skipped` property which is an
+     * array of tiles which could not be downloaded, and a `stats` property which
+     * is an object with the total number of tiles, downloaded tiles, and total
+     * bytes downloaded.
+     *
+     * @param {object} opts
+     * @param {import('./utils/geo.js').BBox} opts.bounds
+     * @param {number} opts.maxzoom
+     * @param {(progress: TileDownloadStats) => void} [opts.onprogress]
+     * @param {boolean} [opts.trackErrors=false] Include errors in the returned array of skipped tiles - this has memory overhead so should only be used for debugging.
+     * @returns {AsyncGenerator<[import('stream').Readable, TileInfo]> & { readonly skipped: Array<TileInfo & { error?: Error }>, readonly stats: TileDownloadStats }}
+     */
+    getTiles({ bounds, maxzoom, onprogress, trackErrors }: {
+        bounds: import("./utils/geo.js").BBox;
+        maxzoom: number;
+        onprogress?: ((progress: TileDownloadStats) => void) | undefined;
+        trackErrors?: boolean | undefined;
+    }): AsyncGenerator<[import("stream").Readable, TileInfo]> & {
+        readonly skipped: Array<TileInfo & {
+            error?: Error;
+        }>;
+        readonly stats: TileDownloadStats;
+    };
+    #private;
+}
+export type ResponsePromise = import("ky").ResponsePromise & {
+    body: ReadableStream<Uint8Array>;
+};
+export type GlyphDownloadStats = {
+    total: number;
+    downloaded: number;
+    totalBytes: number;
+};
+import type { StyleInlinedSources } from './types.js';
+import type { GlyphInfo } from './writer.js';
+import type { TileDownloadStats } from './tile-downloader.js';
+import type { TileInfo } from './writer.js';
+import type { StyleSpecification } from '@maplibre/maplibre-gl-style-spec';

package/dist/tile-downloader.d.ts

@@ -0,0 +1,72 @@
+/** @typedef {Omit<import('./writer.js').TileInfo, 'sourceId'>} TileInfo */
+/**
+ * @typedef {object} TileDownloadStats
+ * @property {number} total
+ * @property {number} downloaded
+ * @property {number} skipped
+ * @property {number} totalBytes
+ */
+/**
+ * Download tiles from a list of tile URLs within a bounding box and zoom range.
+ * Returns an async generator of tile data as readable streams and tile info objects.
+ *
+ * @param {object} opts
+ * @param {string[]} opts.tileUrls Array of tile URL templates. Use `{x}`, `{y}`, `{z}` placeholders, and optional `{scheme}` placeholder which can be `xyz` or `tms`.
+ * @param {import('./utils/geo.js').BBox} opts.bounds Bounding box of the area to download
+ * @param {number} opts.maxzoom Maximum zoom level to download
+ * @param {(progress: TileDownloadStats) => void} [opts.onprogress] Callback to report download progress
+ * @param {boolean} [opts.trackErrors=false] Include errors in the returned array of skipped tiles - this has memory overhead so should only be used for debugging.
+ * @param {import('./utils/geo.js').BBox} [opts.sourceBounds=MAX_BOUNDS] Bounding box of source data.
+ * @param {boolean} [opts.boundsBuffer=false] Buffer the bounds by one tile at each zoom level to ensure no tiles are missed at the edges. With this set to false, in most instances the map will appear incomplete when viewed because the downloaded tiles at lower zoom levels will not cover the map view area.
+ * @param {number} [opts.minzoom=0] Minimum zoom level to download (for most cases this should be left as `0` - the size overhead is minimal, because each zoom level has 4x as many tiles)
+ * @param {number} [opts.concurrency=8] Number of concurrent downloads (ignored if `fetchQueue` is provided)
+ * @param {FetchQueue} [opts.fetchQueue=new FetchQueue(concurrency)] Optional fetch queue to use for downloading tiles
+ * @param {'xyz' | 'tms'} [opts.scheme='xyz'] Tile scheme to use for tile URLs
+ * @returns {AsyncGenerator<[import('stream').Readable, TileInfo]> & { readonly skipped: Array<TileInfo & { error?: Error }>, readonly stats: TileDownloadStats }}
+ */
+export function downloadTiles({ tileUrls, bounds, maxzoom, onprogress, trackErrors, sourceBounds, boundsBuffer, minzoom, concurrency, fetchQueue, scheme, }: {
+    tileUrls: string[];
+    bounds: import("./utils/geo.js").BBox;
+    maxzoom: number;
+    onprogress?: ((progress: TileDownloadStats) => void) | undefined;
+    trackErrors?: boolean | undefined;
+    sourceBounds?: import("./utils/geo.js").BBox | undefined;
+    boundsBuffer?: boolean | undefined;
+    minzoom?: number | undefined;
+    concurrency?: number | undefined;
+    fetchQueue?: FetchQueue | undefined;
+    scheme?: "xyz" | "tms" | undefined;
+}): AsyncGenerator<[import("stream").Readable, TileInfo]> & {
+    readonly skipped: Array<TileInfo & {
+        error?: Error;
+    }>;
+    readonly stats: TileDownloadStats;
+};
+/**
+ *
+ * @param {object} opts
+ * @param {import('./utils/geo.js').BBox} [opts.bounds]
+ * @param {import('./utils/geo.js').BBox} [opts.sourceBounds]
+ * @param {boolean} [opts.boundsBuffer]
+ * @param {number} [opts.minzoom]
+ * @param {number} opts.maxzoom
+ */
+export function tileIterator({ bounds, minzoom, maxzoom, sourceBounds, boundsBuffer, }: {
+    bounds?: import("./utils/geo.js").BBox | undefined;
+    sourceBounds?: import("./utils/geo.js").BBox | undefined;
+    boundsBuffer?: boolean | undefined;
+    minzoom?: number | undefined;
+    maxzoom: number;
+}): Generator<{
+    x: number;
+    y: number;
+    z: number;
+}, void, unknown>;
+export type TileInfo = Omit<import("./writer.js").TileInfo, "sourceId">;
+export type TileDownloadStats = {
+    total: number;
+    downloaded: number;
+    skipped: number;
+    totalBytes: number;
+};
+import { FetchQueue } from './utils/fetch.js';

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+import type { SourceSpecification, StyleSpecification, ValidationError, GeoJSONSourceSpecification, VectorSourceSpecification, RasterSourceSpecification, RasterDEMSourceSpecification } from '@maplibre/maplibre-gl-style-spec';
+import type { GeoJSON, BBox } from 'geojson';
+import type { Readable } from 'stream';
+import type { SetRequired } from 'type-fest';
+import { SUPPORTED_SOURCE_TYPES } from './writer.js';
+export type InputSource = Extract<SourceSpecification, {
+    type: (typeof SUPPORTED_SOURCE_TYPES)[number];
+}>;
+type TransformInlinedSource<T extends SourceSpecification> = T extends GeoJSONSourceSpecification ? OmitUnion<T, 'data'> & {
+    data: GeoJSON;
+} : T extends VectorSourceSpecification | RasterSourceSpecification | RasterDEMSourceSpecification ? SetRequired<OmitUnion<T, 'url'>, 'tiles'> : T;
+/**
+ * This is a slightly stricter version of SourceSpecification that requires
+ * sources to be inlined (e.g. no urls to TileJSON or GeoJSON files).
+ */
+export type InlinedSource = TransformInlinedSource<SourceSpecification>;
+type SupportedInlinedSource = Extract<InlinedSource, {
+    type: (typeof SUPPORTED_SOURCE_TYPES)[number];
+}>;
+/**
+ * This is a slightly stricter version of StyleSpecification that requires
+ * sources to be inlined (e.g. no urls to TileJSON or GeoJSON files).
+ */
+export type StyleInlinedSources = Omit<StyleSpecification, 'sources'> & {
+    sources: {
+        [_: string]: InlinedSource;
+    };
+};
+export type SMPSource = TransformSMPInputSource<SupportedInlinedSource>;
+/**
+ * This is a slightly stricter version of StyleSpecification that is provided in
+ * a Styled Map Package. Tile sources must have tile URLs inlined (they cannot
+ * refer to a TileJSON url), and they must have bounds, minzoom, and maxzoom.
+ * GeoJSON sources must have inlined GeoJSON (not a URL to a GeoJSON file).
+ */
+export type SMPStyle = TransformSMPStyle<StyleSpecification>;
+export type TransformSMPInputSource<T extends SupportedInlinedSource> = T extends GeoJSONSourceSpecification ? T & {
+    data: {
+        bbox: BBox;
+    };
+} : T extends RasterSourceSpecification | VectorSourceSpecification ? SetRequired<T, 'bounds' | 'minzoom' | 'maxzoom'> : T;
+type TransformSMPStyle<T extends StyleSpecification> = Omit<T, 'sources'> & {
+    metadata: {
+        'smp:bounds': [number, number, number, number];
+        'smp:maxzoom': 0;
+        'smp:sourceFolders': {
+            [_: string]: string;
+        };
+    };
+    sources: {
+        [_: string]: SMPSource;
+    };
+};
+export interface ValidateStyle {
+    (style: unknown): style is StyleSpecification;
+    errors: Array<ValidationError>;
+}
+export interface DownloadStream extends Readable {
+    iterator(...args: Parameters<Readable['iterator']>): AsyncIterableIterator<Buffer>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<Buffer>;
+}
+export type RequiredUnion<T> = T extends any ? Required<T> : never;
+export type OmitUnion<T, K extends keyof any> = T extends unknown ? Omit<T, K> : never;
+export {};

package/dist/utils/errors.d.ts

@@ -0,0 +1,6 @@
+export class ENOENT extends Error {
+    /** @param {string} path */
+    constructor(path: string);
+    code: string;
+    path: string;
+}

package/dist/utils/fetch.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @typedef {object} DownloadResponse
+ * @property {import('stream').Readable} body Node ReadableStream of the response body
+ * @property {string | null} mimeType Content mime-type (from http content-type header)
+ * @property {number | null} contentLength Content length in bytes (from http content-length header)
+ */
+/**
+ * A wrapper for fetch that limits the number of concurrent downloads.
+ */
+export class FetchQueue {
+    /** @param {number} concurrency */
+    constructor(concurrency: number);
+    get activeCount(): number;
+    /**
+     * Fetch a URL, limiting the number of concurrent downloads. Resolves with a
+     * `DownloadResponse`, which is a parsed from the Fetch `Response` objects,
+     * with `body` as a Node readable stream, and the MIME type and content length
+     * of the response.
+     *
+     * NB: The response body stream must be consumed to the end, otherwise the
+     * queue will never be emptied.
+     *
+     * @param {string} url
+     * @param {{ onprogress?: import('./streams.js').ProgressCallback }} opts
+     * @returns {Promise<DownloadResponse>}
+     */
+    fetch(url: string, { onprogress }?: {
+        onprogress?: import("./streams.js").ProgressCallback;
+    }): Promise<DownloadResponse>;
+    #private;
+}
+export type DownloadResponse = {
+    /**
+     * Node ReadableStream of the response body
+     */
+    /**
+     * Node ReadableStream of the response body
+     */
+    body: import("stream").Readable;
+    /**
+     * Content mime-type (from http content-type header)
+     */
+    /**
+     * Content mime-type (from http content-type header)
+     */
+    mimeType: string | null;
+    /**
+     * Content length in bytes (from http content-length header)
+     */
+    /**
+     * Content length in bytes (from http content-length header)
+     */
+    contentLength: number | null;
+};

package/dist/utils/file-formats.d.ts

@@ -0,0 +1,25 @@
+/**
+ * For a given buffer, determine the tile format based on the magic bytes.
+ * Will throw for unknown file types.
+ * Smaller and faster version of magic-bytes.js due to the limited use case.
+ *
+ * @param {Buffer | Uint8Array} buf
+ * @returns {import("../writer.js").TileFormat}
+ */
+export function getTileFormatFromBuffer(buf: Buffer | Uint8Array): import("../writer.js").TileFormat;
+/**
+ * Determine the tile format from either a readable stream, buffer or Uint8Array
+ * from the magic bytes at the start of the file. Used if data is served without
+ * a content-type header.
+ *
+ * @param {import('stream').Readable} tileData
+ * @returns {Promise<[import("../writer.js").TileFormat, import('stream').Readable]>}
+ */
+export function getTileFormatFromStream(tileData: import("stream").Readable): Promise<[import("../writer.js").TileFormat, import("stream").Readable]>;
+/**
+ * Get the tile format from a MIME type. Throws for unsupported types.
+ *
+ * @param {string} mimeType
+ * @returns {import("../writer.js").TileFormat}
+ */
+export function getFormatFromMimeType(mimeType: string): import("../writer.js").TileFormat;

package/dist/utils/geo.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @typedef {[number, number, number, number]} BBox
+ */
+/**
+ * Return the bounding box for the given tile.
+ *
+ * @param {{ x: number, y: number, z: number }} tile
+ * @returns {BBox} Bounding Box [w, s, e, n]
+ */
+export function tileToBBox({ x, y, z }: {
+    x: number;
+    y: number;
+    z: number;
+}): BBox;
+/**
+ * @param {{ x: number, y: number, z: number }} tile
+ */
+export function getQuadkey({ x, y, z }: {
+    x: number;
+    y: number;
+    z: number;
+}): string;
+/**
+ * From an array of tile URL templates, get the URL for the given tile.
+ *
+ * @param {string[]} urls
+ * @param {{ x: number, y: number, z: number, scheme?: 'xyz' | 'tms' }} opts
+ */
+export function getTileUrl(urls: string[], { x, y, z, scheme }: {
+    x: number;
+    y: number;
+    z: number;
+    scheme?: "xyz" | "tms";
+}): string;
+/**
+ * Returns a bbox that is the smallest bounding box that contains all the input bboxes.
+ *
+ * @param {[BBox, ...BBox[]]} bboxes
+ * @returns {BBox} Bounding Box [w, s, e, n]
+ */
+export function unionBBox(bboxes: [BBox, ...BBox[]]): BBox;
+/** Spherical Mercator max bounds, rounded to 6 decimal places */
+export const MAX_BOUNDS: BBox;
+export type BBox = [number, number, number, number];

package/dist/utils/mapbox.d.ts

@@ -0,0 +1,40 @@
+/** @param {string} url */
+export function isMapboxURL(url: string): boolean;
+/**
+ * @param {string} url
+ * @param {string} [accessToken]
+ */
+export function normalizeStyleURL(url: string, accessToken?: string | undefined): string;
+/**
+ * @param {string} url
+ * @param {string} [accessToken]
+ */
+export function normalizeGlyphsURL(url: string, accessToken?: string | undefined): string;
+/**
+ * @param {string} url
+ * @param {string} [accessToken]
+ */
+export function normalizeSourceURL(url: string, accessToken?: string | undefined): string;
+/**
+ * @param {string} url
+ * @param {'' | '@2x'} format
+ * @param {'.png' | '.json'} extension
+ * @param {string} [accessToken]
+ */
+export function normalizeSpriteURL(url: string, format: "" | "@2x", extension: ".png" | ".json", accessToken?: string | undefined): string;
+/**
+ * @param {any} tileURL
+ * @param {string} sourceURL
+ * @param {256 | 512} [tileSize]
+ * @param {{ devicePixelRatio?: number; supportsWebp?: boolean; }} [opts]
+ */
+export function normalizeTileURL(tileURL: any, sourceURL: string, tileSize?: 256 | 512 | undefined, { devicePixelRatio, supportsWebp }?: {
+    devicePixelRatio?: number;
+    supportsWebp?: boolean;
+} | undefined): any;
+export type URLObject = {
+    protocol: string;
+    authority: string;
+    path: string;
+    params: string[];
+};

package/dist/utils/misc.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Dumb and quick clone an object. Won't keep undefined properties. Types could
+ * be tighted so that return type excludes undefined properties, but not really
+ * needed.
+ *
+ * @template T
+ * @param {T} obj
+ * @returns {T}
+ */
+export function clone<T>(obj: T): T;
+export function noop(): void;
+/**
+ * Like `Object.hasOwn`, but refines the type of `key`.
+ *
+ * @template {Record<string, unknown>} T
+ * @param {T} obj
+ * @param {string} key
+ * @returns {key is (keyof T)}
+ */
+export function hasOwn<T extends Record<string, unknown>>(obj: T, key: string): key is (keyof T);

package/dist/utils/streams.d.ts

@@ -0,0 +1,69 @@
+/** @import { TransformOptions } from 'readable-stream' */
+/**
+ * Create a writable stream from an async function. Default concurrecy is 16 -
+ * this is the number of parallel functions that will be pending before
+ * backpressure is applied on the stream.
+ *
+ * @template {(...args: any[]) => Promise<void>} T
+ * @param {T} fn
+ * @returns {import('readable-stream').Writable}
+ */
+export function writeStreamFromAsync<T extends (...args: any[]) => Promise<void>>(fn: T, { concurrency }?: {
+    concurrency?: number | undefined;
+}): import("readable-stream").Writable;
+/**
+ * From https://github.com/nodejs/node/blob/430c0269/lib/internal/webstreams/adapters.js#L509
+ *
+ * @param {ReadableStream} readableStream
+ * @param {{
+ *   highWaterMark? : number,
+ *   encoding? : string,
+ *   objectMode? : boolean,
+ *   signal? : AbortSignal,
+ * }} [options]
+ * @returns {import('stream').Readable}
+ */
+export function fromWebReadableStream(readableStream: ReadableStream, options?: {
+    highWaterMark?: number;
+    encoding?: string;
+    objectMode?: boolean;
+    signal?: AbortSignal;
+} | undefined): import("stream").Readable;
+/**
+ * @param {unknown} obj
+ * @returns {obj is ReadableStream}
+ */
+export function isWebReadableStream(obj: unknown): obj is ReadableStream;
+/** @typedef {(opts: { totalBytes: number, chunkBytes: number }) => void} ProgressCallback */
+/** @typedef {TransformOptions & { onprogress?: ProgressCallback }} ProgressStreamOptions */
+/**
+ * Passthrough stream that counts the bytes passing through it. Pass an optional
+ * `onprogress` callback that will be called with the accumulated total byte
+ * count and the chunk byte count after each chunk.
+ * @extends {Transform}
+ */
+export class ProgressStream extends Transform {
+    /**
+     * @param {ProgressStreamOptions} [opts]
+     */
+    constructor({ onprogress, ...opts }?: ProgressStreamOptions | undefined);
+    /** Total bytes that have passed through this stream */
+    get byteLength(): number;
+    /**
+     * @override
+     * @param {Buffer | Uint8Array} chunk
+     * @param {Parameters<Transform['_transform']>[1]} encoding
+     * @param {Parameters<Transform['_transform']>[2]} callback
+     */
+    override _transform(chunk: Buffer | Uint8Array, encoding: Parameters<Transform["_transform"]>[1], callback: Parameters<Transform["_transform"]>[2]): void;
+    #private;
+}
+export type ProgressCallback = (opts: {
+    totalBytes: number;
+    chunkBytes: number;
+}) => void;
+export type ProgressStreamOptions = TransformOptions & {
+    onprogress?: ProgressCallback;
+};
+import { Transform } from 'readable-stream';
+import type { TransformOptions } from 'readable-stream';