diff --git a/README.md b/README.md index 994cca3..c75cabc 100644 --- a/README.md +++ b/README.md @@ -87,6 +87,7 @@ With 10 simultaneous downloads. Retrying each one to a max of 10. - `hash`: <[string][]> Hash algorithm to use to create a [crypto.Hash][] instance computing the stream hash. - `use`: <[object][]> Key-value pairs of middlewares with which to pipe the response object through. keys are [strings][string], values are [Transformer generating functions](#usemiddlewarefn) (Alternatively, use the [xget.use()](#xgetuse) method). - `with`: <[object][]> Key-value pairs of middlewares with which to pipe the dataslice object through. keys are [strings][string], values are [functions][function] whose return values are accessible within the [store](#storestack). (Alternatively, use the [xget.with()](#xgetwith) method). +- `headHandler`: <[HeadHandler](#headhandler)> An interceptor for the initial HEAD data, useful for programmatically defining a range offset; ### xget.store: [`Map`][map] @@ -195,6 +196,13 @@ This ensures you can get a hash of an instancce of the data even while still str Returns the hash algorithm if any is in use. +### xget.setHeadHandler() + +- `fn`: <[HeadHandler](#headhandler)> Handler to be set. +- Returns: <[boolean][]> Whether or not the handler was successfully set. + +Sets an interceptor for the initial HEAD data, useful for programmatically defining a range offset. Returns `false` if the request has already been loaded, `true` if successfully set. + ### xget.use(tag, handler) - `tag`: <[string][]> @@ -255,13 +263,24 @@ xget(URL) ``` +### HeadHandler: [`function`][function] + +- `props`: <[object][]> + - `headers`: <[IncomingHttpHeaders][incominghttpheaders]> HEAD headers from the URL. + - `acceptsRanges`: <[boolean][]> Whether or not the URL resource accepts byte ranges. +- Returns: <[number] | void> An offset to begin streaming from. Analogous to `.start`. If void, defaults to `.start` or `0`; + +An interceptor for the initial HEAD data, useful for programmatically defining a range offset. + ### LoadData: [`Object`][object] - `url`: <[string][]> The URL specified. - `size`: <[number][]> Finite number returned if server responds appropriately, else `Infinity`. - `start`: <[number][]> Sticks to specification if server allows chunking via `content-ranges` else, resets to `0`. - `chunkable`: <[number][]> Whether or not the URL feed can be chunked, supporting simultaneous connections. +- `totalSize`: <[number]> Actual size of the resource without an offset. - `chunkStack`: <[ChunkLoadInstance](#chunkloadinstance)[]> The chunkstack array. +- `headers`: <[IncomingHttpHeaders][incominghttpheaders]> The recieved array. ### ChunkLoadInstance: [`Object`][object] diff --git a/typings/index.d.ts b/typings/index.d.ts index 361dccc..6142b35 100644 --- a/typings/index.d.ts +++ b/typings/index.d.ts @@ -34,6 +34,7 @@ declare namespace xget { getHash(): Buffer; getHash(encoding: string): string; getHashAlgorithm(): string; + setHeadHandler(fn: HeadHandler): boolean; use(tag: string, fn: UseMiddlewareFn): this; with(tag: string, fn: WithMiddlewareFn): this; getErrContext(err: Error): { raw: Error, tag: string, source: 'xget:with' | 'xget:use' } @@ -53,6 +54,7 @@ declare namespace xget { chunks: number; retries: number; timeout: number; + headHandler: HeadHandler; } interface ChunkLoadInstance { @@ -74,12 +76,14 @@ declare namespace xget { size: number; start: number; chunkable: boolean; + totalSize: number; chunkStack: ChunkLoadInstance[]; headers: IncomingHttpHeaders; } type MiddlewareStore = Map; + type HeadHandler = (props: {headers: IncomingHttpHeaders, acceptsRanges: boolean}) => number | void; type UseMiddlewareFn = (dataSlice: ChunkLoadInstance, store: MiddlewareStore) => NodeJS.ReadWriteStream; type WithMiddlewareFn = (loadData: LoadDataSlice) => any;