observablehq-file-attachments/lib/esm/util.d.ts

Library to handle ObservableHQ's file attachments more flexibly, and to support virtualizing them.

/**
 * General utilities
 * @module util
 */
import { FileAttachment, Files, Metadata, Tree, Version, VFile, DataOptions } from "./types";
import { AFile } from "./AFile";
/**
 * like 'throw', but a function rather than a statement.
 * @param e The exception or string to be thrown.
 */
export declare const Throw: (e: Error | string) => never;
/**
 * A type guard to distinguish directory trees and file arrays.
 * @param t The object, which should be a directory tree or a files array
 * @returns `true` if the argument is a `Files` array
 */
export declare const isFiles: (t?: Tree | Files | undefined) => t is Files;
/**
 * A type guard to distinguish directory trees and file arrays.
 * @param t The object, which should be a directory tree or a files array
 * @returns `true` if the argument is a `Tree`
 */
export declare const isTree: (t?: Tree | Files | undefined) => t is Tree;
/**
 * A type checker that verifies the argument is a file array, not a directory tree.
 * Throws an error if given something else
 * @param t A tree or a file array
 * @returns A file array or `null` if the argument was undefined
 */
export declare const asFiles: (t?: Tree | Files | undefined) => Files | null;
/**
 * A type checker that verifies the argument is a tree, not a file array. Throws an error
 * if given something else.
 * @param t A tree or a file array
 * @returns Tree or `null` if the argument was undefined.
 */
export declare const asTree: (t?: Tree | Files | undefined) => Tree | null;
/**
 * A type guard that determines if the argument is a [FileAttachment](https://observablehq.com/@observablehq/file-attachments)
 * @param a A [FileAttachment](https://observablehq.com/@observablehq/file-attachments) or [[AFile]]
 * @returns `true` if argument is a [FileAttachment](https://observablehq.com/@observablehq/file-attachments)
 */
export declare const isFileAttachment: (a: any) => a is FileAttachment;
/**
 * Add a file at a specific version or label in a [[Files]] array.
 * This is an internal tool for implementing [[FILE]] handlers.
 * @param files The Files array
 * @param version The version to delete. Either a version number or a label
 * @returns void
 */
export declare const getVersion: (files: Files, version: Version) => VFile | null;
/**
 * Wrap an [[AFile]] in a [[Files]] version array, with the specified
 * versions or labels assigned to it.
 * @param file the [[AFile]]
 * @param versions zero or more [[Version]]s (positive numbers or strings)
 * @returns a [[Files]] array.
 */
export declare const versions: (file: AFile, ...versionList: Version[]) => Files;
/**
 * Convenience method to construct an entry in a [[AFileSystem]] tree.
 * Takes a name and a data item, optional metadata, and list of versions,
 * and constructs the appropriate [[Files]] array for the tree.
 *
 * Simplest usage:
 * ```javascript
 * F = new AFileSystem({
 *   myFile: file('myFile', (myData));
 * });
 *
 * Advanced usage that supplies a creation date as metadata, and gives the file
 * a version of 1 and a label of 'tested';
 * ```javascript
 * F = new AFileSystem({
 *   myFile: file('myFile', (myData), {creationDate}, 1, 'tested');
 * });
 * ```
 * @param name The name of the file
 * @param data The data to store
 * @param metadata The metadata to associate with both array and file
 * @param versionList A list of versions to store the file under, or `[1]`.
 * @returns
 */
export declare function file(name: string, data: any, metadata?: Partial<Metadata> | null | undefined, ...versionList: Version[]): Files;
export declare function file(name: string, data: any, ...versionList: Version[]): Files;
/**
 * Convenience method to construct an entry in a [[AFileSystem]] tree,
 * without having to specifiy the name multiple times.
 * Takes a name and a data item, optional metadata, and list of versions,
 * and constructs the appropriate [[Files]] array for the tree.
 *
 * Simplest usage:
 * ```javascript
 * F = new AFileSystem({
 *   myFile: file('myFile', (myData));
 * });
 *
 * Advanced usage that supplies a creation date as metadata, and gives the file
 * a version of 1 and a label of 'tested';
 * ```javascript
 * F = new AFileSystem({
 *   ...entry('myFile', (myData), {creationDate}, 1, 'tested');
 * });
 * ```
 * @param name The name of the file
 * @param data The data to store
 * @param metadata The metadata to associate with both array and file
 * @param versionList A list of versions to store the file under, or `[1]`.
 * @returns
 */
export declare function entry(name: string, data: any, metadata?: Partial<Metadata> | null | undefined, ...versionList: Version[]): Tree;
export declare function entry(name: string, data: any, ...versionList: Version[]): Tree;
/**
 * Add a file at a specific version or label in a [[Files]] array.
 * This is an internal tool for implementing [[FILE]] handlers.
 * @param files The Files array
 * @param version The version to set. Either a version number or a label
 * @param newFile The [FileAttachment](https://observablehq.com/@observablehq/file-attachments) or [[AFile]]
 * @returns void
 */
export declare const setVersion: (files: Files, version: Version, newFile: VFile) => void;
/**
 * Delete a specific version from a [[Files]] array. This is an internal tool for implementing
 * [[FILE]] handlers
 * @param files The Files array
 * @param version The version to delete. Either a version number or a label. The special label '*' deletes all versions.
 * @returns void
 */
export declare const deleteVersion: (files: Files, version: Version) => void;
/**
 * Encode a `string` into an `ArrayBuffer`.
 * @param s The `string` to be encoded
 * @returns An `ArrayBuffer` with the string data as UTF-16
 */
export declare const encodeString16: (s: string) => ArrayBuffer;
/**
 * Convert a `string` to an `ArrayBuffer`, in either UTF8 or UTF16 formats.
 * @param s
 * @param param1
 * @returns an `ArrayBuffer` with the `string`'s content in the requested format.
 */
export declare const toArrayBuffer: (s: string, { utf8 }?: DataOptions) => ArrayBufferLike;
/**
 * Convert an `ArrayBuffer` to a `string`.
 * @param ab An `ArrayBuffer`
 * @param param1
 * @returns the string
 */
export declare const fromArrayBuffer: (ab: ArrayBuffer, { utf8 }?: DataOptions) => string;
/**
 * Associate a _metadata_ object with the specified file (or array of file
 * versions). This is normally used to annotate entries in the [[AFileSystem]]
 * tree.
 */
export declare const meta: <T>(obj: T, metadata: Metadata) => any;
/**
 *
 * @param data The data to be parsed
 * @param delimiter The field delimiter, either `"\t"` or `","`.
 * @param options
 * @returns
 */
export declare function dsv(data: string, delimiter: '\t' | ',', { array, typed, utf8 }?: DataOptions): object[];
//# sourceMappingURL=util.d.ts.map