s2-tools/dist/readers/protobuf/index.d.ts

A collection of geospatial tools primarily designed for WGS84, Web Mercator, and S2.

/**
 * User defined function to read in fields from a Pbf instance into input.
 * @template U - the input type
 */
export type ReadFieldFunction<U> = (tag: number, input: U, pbf: Pbf) => void;
/**
 * A tag is a pair of a number and a type.
 */
export interface Tag {
    /** the number of the tag */
    tag: number;
    /** the type of the tag */
    type: number;
}
/**
 * # Protobuffer
 *
 * ## Description
 * Create a new PBF instance and either read or write to it.
 * Follows the early Protobuf spec supporting various types of encoding
 * including messages (which are usually representative of class objects).
 *
 * ## Usage
 *
 * ### Reading:
 * ```ts
 * const data = fs.readFileSync(path);
 * const pbf = new Pbf(data);
 * ```
 *
 * ### Writing:
 * ```ts
 * const pbf = new Pbf();
 * pbf.writeVarintField(1, 1);
 * // ...
 * const result = pbf.commit();
 * ```
 */
export declare class Pbf {
    buf: Uint8Array;
    pos: number;
    length: number;
    type: number;
    static Varint: number;
    static Fixed64: number;
    static Bytes: number;
    static Fixed32: number;
    static None: number;
    /**
     * @param buf - an optional Uint8Array to use for reading. otherwise defaults to an empty
     * Uint8Array for writing
     */
    constructor(buf?: Uint8Array);
    /**
     * Destroys the PBF instance. You can still use the Pbf instance after calling
     * this method. However, the buffer will be emptied.
     */
    destroy(): void;
    /**
     * Reads a tag from the buffer, pulls out the tag and type and returns it.
     * @returns - {tag: number, type: number}
     */
    readTag(): Tag;
    /**
     * If you know you are reading a message, but have already read the length of
     * the message OR you're reading fields of the top level data, then this method
     * is the alternative. It's often used by sub-classes So that it can be
     * instationated prior to reading the message. @see {@link readMessage}.
     *
     * Ex.
     *
     * ```ts
     * export class MapboxVectorLayer {
     *   constructor(pbf: Protobuf, end: number) {
     *     this.#pbf = pbf;
     *     pbf.readFields(this.#readLayer, this, end);
     *   }
     *
     *   #readLayer(tag: number, layer: MapboxVectorLayer, pbf: Protobuf): void {
     *     if (tag === 15) layer.version = pbf.readVarint();
     *     else if (tag === 1) layer.name = pbf.readString();
     *     ...
     *   }
     * }
     * ```
     * @param readField - user defined input function to parse the message fields
     * @param input - The class to mutate given field data
     * @param end - the end position of the message in the buffer
     * @returns - The class we mutated will be returned
     */
    readFields<U>(readField: ReadFieldFunction<U>, input: U, end: number): U;
    /**
     * Reads a message from the buffer. Sometimes it's easier to manage sub structures
     * so that the current method can build multiples of an entire structure/class.
     * If you you are at the top level, or parsing the message inside a class, then
     * @see {@link readFields}.
     *
     * Ex.
     *
     * ```ts
     * class Test {
     *   a: number = 0;
     *
     *   static read(tag: number, test: Test, pbf: Protobuf): void {
     *     if (tag === 1) test.a = pbf.readVarint();
     *     // ...
     *   }
     * }
     *
     * const pbf = new Pbf(data);
     * const t = new Test();
     * pbf3.readTag();
     * pbf3.readMessage(Test.read, t);
     * ```
     * @param readField - user defined input function
     * @param input - an instance of the class you are reading into
     * @returns - The class itself will be returned
     */
    readMessage<U>(readField: ReadFieldFunction<U>, input: U): U;
    /**
     * Read in a 32-bit unsigned integer from the buffer. There are no compression advantages
     * with this type of encoding.
     * @returns - 32-bit unsigned integer
     */
    readFixed32(): number;
    /**
     * Read in a 32-bit signed integer from the buffer. There are no compression advantages
     * with this type of encoding.
     * @returns - 32-bit signed integer
     */
    readSFixed32(): number;
    /**
     * Read in a 64-bit unsigned integer from the buffer. There are no compression advantages
     * with this type of encoding.
     * @returns - 64-bit unsigned integer
     */
    readFixed64(): number;
    /**
     * Read in a 64-bit signed integer from the buffer. There are no compression advantages
     * with this type of encoding.
     * @returns - 64-bit signed integer
     */
    readSFixed64(): number;
    /**
     * Read in a 32-bit float from the buffer. There are no compression advantages
     * with this type of encoding.
     * @returns - 32-bit float
     */
    readFloat(): number;
    /**
     * Read in a 64-bit float from the buffer. There are no compression advantages
     * with this type of encoding.
     * @returns - 64-bit float
     */
    readDouble(): number;
    /**
     * @param isSigned - true if the number is signed
     * @returns - the decoded number
     */
    readVarint(isSigned?: boolean): number;
    /**
     * @see {@link readVarint} for better performance
     * @returns - the decoded number
     */
    readVarint64(): number;
    /**
     * @returns - the decoded number as a signed number
     */
    readSVarint(): number;
    /**
     * @returns - parses the varint byte as a boolean expression
     */
    readBoolean(): boolean;
    /**
     * @returns - the decoded string
     */
    readString(): string;
    /**
     * NOTE: bytes is preceeded by a varint dscribing the length of the bytes.
     * The bytes themselves are presumed to be u8s and therefore don't need to be decoded
     * @returns - the decoded byte array
     */
    readBytes(): Uint8Array;
    /**
     * @param arr - the array to write to
     * @param isSigned - true if the numbers are signed
     * @returns - the `arr` input with the decoded numbers is also returned
     */
    readPackedVarint(arr?: number[], isSigned?: boolean): number[];
    /**
     * @param arr - the array to write to
     * @returns - the `arr` input with the decoded numbers is also returned
     */
    readPackedSVarint(arr?: number[]): number[];
    /**
     * @param arr - the array to write to
     * @returns - the `arr` input with the decoded boolean values is also returned
     */
    readPackedBoolean(arr?: boolean[]): boolean[];
    /**
     * @param arr - the array to write to
     * @returns - the `arr` input with the decoded floats is also returned
     */
    readPackedFloat(arr?: number[]): number[];
    /**
     * @param arr - the array to write to
     * @returns - the `arr` input with the decoded doubles is also returned
     */
    readPackedDouble(arr?: number[]): number[];
    /**
     * @param arr - the array to write to
     * @returns - the `arr` input with the decoded unsigned integers is also returned
     */
    readPackedFixed32(arr?: number[]): number[];
    /**
     * @param arr - the array to write to
     * @returns - the `arr` input with the decoded signed integers is also returned
     */
    readPackedSFixed32(arr?: number[]): number[];
    /**
     * @param arr - the array to write to
     * @returns - the `arr` input with the decoded unsigned 64-bit integers is also returned
     */
    readPackedFixed64(arr?: number[]): number[];
    /**
     * @param arr - the array to write to
     * @returns - the `arr` input with the decoded signed 64-bit integers is also returned
     */
    readPackedSFixed64(arr?: number[]): number[];
    /**
     * Skip a value we are not interested in parsing
     * @param val - the type to skip
     */
    skip(val: number): void;
    /**
     * Write a tag and its associated type
     * @param tag - the tag to write
     * @param type - the type to write  (will never be greater than 3 bits)
     */
    writeTag(tag: number, type: number): void;
    /**
     * Allocate more space in the buffer
     * @param min - the minimum number of bytes to allocate
     */
    realloc(min: number): void;
    /**
     * @returns - the entire written buffer
     */
    commit(): Uint8Array;
    /**
     * Write a 32-bit unsigned integer
     * @param val - the 32-bit unsigned integer to write
     */
    writeFixed32(val: number): void;
    /**
     * Write a 32-bit signed integer
     * @param val - the 32-bit signed integer to write
     */
    writeSFixed32(val: number): void;
    /**
     * Write a 64-bit unsigned integer
     * @param val - the 64-bit unsigned integer to write
     */
    writeFixed64(val: number): void;
    /**
     * Write a 64-bit signed integer
     * @param val - the 64-bit signed integer to write
     */
    writeSFixed64(val: number): void;
    /**
     * Write a varint. Can be max 64-bits. Numbers are coerced to an unsigned
     * while number before using this function.
     * @param val - any whole unsigned number. It's usually best practice to
     * not use this function directly unless you know what you're doing.
     */
    writeVarint(val: number): void;
    /**
     * Write a signed varint. Can be max 64-bits. Numbers can be negative
     * but must still be a while number.
     * @param val - any whole signed number. It's usually best practice to
     * not use this function directly unless you know what you're doing.
     */
    writeSVarint(val: number): void;
    /**
     * Write a boolean value. Can also be a number, in which case
     * it will be converted to a boolean. 0 is false, anything else is true.
     * @param val - the boolean to write.
     */
    writeBoolean(val: boolean | number): void;
    /**
     * Write a string. Strings larger then 128 bytes will be written
     * in chunks of 128 bytes and are slightly less efficient.
     * @param str - the string to write
     */
    writeString(str: string): void;
    /**
     * Write a 32-bit floating point number
     * @param val - a 32-bit floating point number to write
     */
    writeFloat(val: number): void;
    /**
     * Write a 64-bit floating point number
     * @param val - a 64-bit floating point number to write
     */
    writeDouble(val: number): void;
    /**
     * Write a byte array
     * @param buf - a Buffer to write. Will write the length of the buffer first.
     * After that, the buffer will be written byte by byte.
     */
    writeBytes(buf: Buffer): void;
    /**
     * Write a message to the buffer. Allows you to pass in an object
     * with a write function to define how the message should be written.
     * A good tool to abstract away storing classes or sub-classes.
     * @param fn - the user defined function to call to write the message
     * @param obj - the object to pass to the user defined function
     */
    writeRawMessage<T>(fn: (obj: T, pbf: Pbf) => void, obj: T): void;
    /**
     * Write a message to the buffer. Allows you to pass in an object
     * with a write function to define how the message should be written.
     * A good tool to abstract away storing classes or sub-classes.
     * @param tag - the tag to write to associate with the message. This will help track how to
     * read following data.
     * @param fn - user defined function to call to manually define how to write the object
     * @param obj - the object to pass to the user defined function
     */
    writeMessage<T>(tag: number, fn: (obj: T, pbf: Pbf) => void, obj: T): void;
    /**
     * Write a packed repeated unsigned whole number array to the buffer.
     * @param tag - the tag to write to associate with the value.
     * @param arr - the array of unsigned whole numbers to write.
     */
    writePackedVarint(tag: number, arr: number[]): void;
    /**
     * Write a packed repeated signed whole number array to the buffer.
     * @param tag - the tag to write to associate with the value.
     * @param arr - the array of signed whole numbers to write.
     */
    writePackedSVarint(tag: number, arr: number[]): void;
    /**
     * Write a packed repeated boolean array to the buffer.
     * Supports numbers: `0` is false, everything else is true.
     * @param tag - the tag to write to associate with the value.
     * @param arr - the array of booleans to write.
     */
    writePackedBoolean(tag: number, arr: (number | boolean)[]): void;
    /**
     * Write a packed repeated 32-bit float array to the buffer.
     * @param tag - the tag to write to associate with the value.
     * @param arr - the array of floats to write.
     */
    writePackedFloat(tag: number, arr: number[]): void;
    /**
     * Write a packed repeated 64-bit double array to the buffer.
     * @param tag - the tag to write to associate with the value.
     * @param arr - the array of doubles to write.
     */
    writePackedDouble(tag: number, arr: number[]): void;
    /**
     * Write a packed repeated 32-bit unsigned integer array to the buffer.
     * @param tag - the tag to write to associate with the value.
     * @param arr - the array of unsigned 32-bit numbers to write.
     */
    writePackedFixed32(tag: number, arr: number[]): void;
    /**
     * Write a packed repeated 32-bit signed integer array to the buffer.
     * @param tag - the tag to write to associate with the value.
     * @param arr - the array of signed 32-bit numbers to write.
     */
    writePackedSFixed32(tag: number, arr: number[]): void;
    /**
     * Write a packed repeated 64-bit unsigned integer array to the buffer.
     * @param tag - the tag to write to associate with the value.
     * @param arr - the array of unsigned 64-bit numbers to write.
     */
    writePackedFixed64(tag: number, arr: number[]): void;
    /**
     * Write a packed repeated 64-bit signed integer array to the buffer.
     * @param tag - the tag to write to associate with the value.
     * @param arr - the array of signed 64-bit numbers to write.
     */
    writePackedSFixed64(tag: number, arr: number[]): void;
    /**
     * Write a packed repeated byte array to the buffer with
     * an associated tag.
     * @param tag - the tag to write to associate with the value.
     * @param buffer - the buffer of bytes to write.
     */
    writeBytesField(tag: number, buffer: Buffer): void;
    /**
     * write a packed repeated fixed 32-bit integer array to the buffer
     * with an associated tag.
     * @param tag - the tag to write to associate with the value.
     * @param val - the unsigned 32-bit integer to write.
     */
    writeFixed32Field(tag: number, val: number): void;
    /**
     * Write a packed repeated signed 32-bit integer array to the buffer
     * with an associated tag.
     * @param tag - the tag to write to associate with the value.
     * @param val - the signed 32-bit integer to write.
     */
    writeSFixed32Field(tag: number, val: number): void;
    /**
     * Write a packed repeated unsigned 64-bit integer array to the buffer
     * with an associated tag.
     * @param tag - the tag to write to associate with the value.
     * @param val - the unsigned 64-bit integer to write.
     */
    writeFixed64Field(tag: number, val: number): void;
    /**
     * Write a packed repeated signed 64-bit integer array to the buffer
     * with an associated tag.
     * @param tag - the tag to write to associate with the value.
     * @param val - the signed 64-bit integer to write.
     */
    writeSFixed64Field(tag: number, val: number): void;
    /**
     * Write a packed repeated unsigned integer array to the buffer
     * with an associated tag.
     * @param tag - the tag to write to associate with the value.
     * @param val - the unsigned number to write.
     */
    writeVarintField(tag: number, val: number): void;
    /**
     * Write a packed repeated signed integer array to the buffer
     * with an associated tag.
     * @param tag - the tag to write to associate with the value.
     * @param val - the signed number to write.
     */
    writeSVarintField(tag: number, val: number): void;
    /**
     * Write a packed repeated string array to the buffer
     * with an associated tag.
     * @param tag - the tag to write to associate with the value.
     * @param str - the string to write.
     */
    writeStringField(tag: number, str: string): void;
    /**
     * Write a packed repeated float array to the buffer
     * with an associated tag.
     * @param tag - the tag to write to associate with the value.
     * @param val - the float to write.
     */
    writeFloatField(tag: number, val: number): void;
    /**
     * Write a packed repeated double array to the buffer
     * with an associated tag.
     * @param tag - the tag to write to associate with the value.
     * @param val - the double to write.
     */
    writeDoubleField(tag: number, val: number): void;
    /**
     * Write a packed repeated boolean array to the buffer
     * with an associated tag.
     * @param tag - the tag to write to associate with the value.
     * @param val - the boolean to write.
     */
    writeBooleanField(tag: number, val: boolean | number): void;
}
//# sourceMappingURL=index.d.ts.map