roaring/index.d.ts

CRoaring official port for NodeJS

/*
Copyright 2018 Salvatore Previti

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Source code at: https://github.com/SalvatorePreviti/roaring-node 

Documentation at: https://salvatorepreviti.github.io/roaring-node/modules.html

Roaring Bitmap 32 documentation at: https://salvatorepreviti.github.io/roaring-node/classes/RoaringBitmap32.html

*/

import roaring = require("./");

export interface ReadonlySetLike<T> {
  /**
   * Despite its name, returns an iterator of the values in the set-like.
   */
  keys(): Iterator<T>;
  /**
   * @returns a boolean indicating whether an element with the specified value exists in the set-like or not.
   */
  has(value: T): boolean;
  /**
   * @returns the number of (unique) elements in the set-like.
   */
  readonly size: number;
}

/** Gets the approximate memory allocated by the roaring bitmap library. */
export function getRoaringUsedMemory(): number;

/**
 * Creates a new buffer with the given size and alignment.
 * If alignment is not specified, the default alignment of 32 is used.
 * The buffer does not come from the nodejs buffer pool, it is allocated using aligned_malloc.
 *
 * Is the same as Buffer.alloc but is aligned.
 * We need an aligned buffer to create a roaring bitmap frozen view.
 *
 * @param {number} size The size of the buffer to allocate.
 * @param {number} [alignment=32] The alignment of the buffer to allocate.
 */
export function bufferAlignedAlloc(size: number, alignment?: number): Buffer;

/**
 * Creates a new buffer not initialized with the given size and alignment.
 * If alignment is not specified, the default alignment of 32 is used.
 * The buffer does not come from the nodejs buffer pool, it is allocated using aligned_malloc.
 *
 * Is the same as Buffer.allocUnsafe but is aligned.
 * We need an aligned buffer to create a roaring bitmap frozen view.
 *
 * WARNING: this function is unsafe because the returned buffer may contain previously unallocated memory that may contain sensitive data.
 *
 * @param {number} size The size of the buffer to allocate.
 * @param {number} [alignment=32] The alignment of the buffer to allocate.
 */
export function bufferAlignedAllocUnsafe(size: number, alignment?: number): Buffer;

/**
 * Creates a new buffer backed by a SharedArrayBuffer with the given size and alignment.
 * If alignment is not specified, the default alignment of 32 is used.
 * The buffer does not come from the nodejs buffer pool, it is allocated using aligned_malloc.
 *
 * Is the same as Buffer.alloc but is aligned and uses a SharedArrayBuffer as storage.
 * We need an aligned buffer to create a roaring bitmap frozen view.
 *
 * @param {number} size The size of the buffer to allocate.
 * @param {number} [alignment=32] The alignment of the buffer to allocate.
 */
export function bufferAlignedAllocShared(size: number, alignment?: number): Buffer;

/**
 * Creates a new buffer backed by a SharedArrayBuffer with the given size and alignment.
 * If alignment is not specified, the default alignment of 32 is used.
 * The buffer does not come from the nodejs buffer pool, it is allocated using aligned_malloc.
 *
 * Is the same as Buffer.allocUnsafe but is aligned and uses a SharedArrayBuffer as storage.
 * We need an aligned buffer to create a roaring bitmap frozen view.
 *
 * WARNING: this function is unsafe because the returned buffer may contain previously unallocated memory that may contain sensitive data.
 *
 * @param {number} size The size of the buffer to allocate.
 * @param {number} [alignment=32] The alignment of the buffer to allocate.
 */
export function bufferAlignedAllocSharedUnsafe(size: number, alignment?: number): Buffer;

/**
 * Given some kind of buffer or array buffer, returns a nodejs Buffer instance that contains the same data.
 * The underlying ArrayBuffer is the same.
 *
 * @param buffer The source
 * @returns A nodejs Buffer instance that contains the same data.
 */
export function asBuffer(buffer: Buffer | ArrayBufferView | TypedArray | ArrayBuffer | SharedArrayBuffer): Buffer;

export type TypedArray =
  | Uint8Array
  | Uint16Array
  | Uint32Array
  | Uint8ClampedArray
  | Int8Array
  | Int16Array
  | Int32Array
  | Float32Array
  | Float64Array;

/**
 * Checks if the given buffer is memory aligned.
 * If alignment is not specified, the default alignment of 32 is used.
 *
 * @param {TypedArray | Buffer | ArrayBuffer | SharedArrayBuffer | null | undefined} buffer The buffer to check.
 * @param {number} [alignment=32] The alignment to check.
 */
export function isBufferAligned(
  buffer: TypedArray | Buffer | ArrayBuffer | SharedArrayBuffer | null | undefined,
  alignment?: number,
): boolean;

/**
 * Ensures that the given buffer is aligned to the given alignment.
 * If alignment is not specified, the default alignment of 32 is used.
 * If the buffer is already aligned, it is returned.
 * If the buffer is not aligned, a new aligned buffer is created with bufferAlignedAllocUnsafe or bufferAlignedAllocShared and the data is copied.
 *
 * @param {Buffer} buffer The buffer to align.
 * @param {number} [alignment=32] The alignment to align to.
 * @returns {Buffer} The aligned buffer. Can be the same as the input buffer if it was already aligned. Can be a new buffer if the input buffer was not aligned.
 * @memberof RoaringBitmap32
 */
export function ensureBufferAligned(
  buffer: Buffer | Uint8Array | Uint8ClampedArray | SharedArrayBuffer | Int8Array | ArrayBuffer,
  alignment?: number,
): Buffer;

export enum SerializationFormat {
  /**
   * Stable Optimized non portable C/C++ format. Used by croaring. Can be smaller than the portable format.
   */
  croaring = "croaring",

  /**
   * Stable Portable Java and Go format.
   */
  portable = "portable",

  /**
   * Non portable C/C++ frozen format.
   * Is considered unsafe and unstable because the format might change at any new version.
   * Can be useful for temporary storage or for sending data over the network between similar machines.
   * If the content is corrupted when deserialized or when a frozen view is create, the behavior is undefined!
   * The application may crash, buffer overrun, could be a vector of attack!
   *
   * When this option is used in the serialize function, the new returned buffer (if no buffer was provided) will be aligned to a 32 bytes boundary.
   * This is required to create a frozen view with the method unsafeFrozenView.
   *
   */
  unsafe_frozen_croaring = "unsafe_frozen_croaring",

  /**
   * A plain binary array of 32 bits integers in little endian format. 4 bytes per value.
   */
  uint32_array = "uint32_array",
}

export enum FileSerializationFormat {
  /**
   * Stable Optimized non portable C/C++ format. Used by croaring. Can be smaller than the portable format.
   */
  croaring = "croaring",

  /**
   * Stable Portable Java and Go format.
   */
  portable = "portable",

  /**
   * A plain binary array of 32 bits integers in little endian format. 4 bytes per value.
   */
  uint32_array = "uint32_array",

  /**
   * Non portable C/C++ frozen format.
   * Is considered unsafe and unstable because the format might change at any new version.
   * Can be useful for temporary storage or for sending data over the network between similar machines.
   * If the content is corrupted when deserialized or when a frozen view is create, the behavior is undefined!
   * The application may crash, buffer overrun, could be a vector of attack!
   *
   * When this option is used in the serialize function, the new returned buffer (if no buffer was provided) will be aligned to a 32 bytes boundary.
   * This is required to create a frozen view with the method unsafeFrozenView.
   *
   */
  unsafe_frozen_croaring = "unsafe_frozen_croaring",

  /**
   * Comma separated values, all values are in decimal and in one line without spaces or other characters.
   */
  comma_separated_values = "comma_separated_values",

  /**
   * Tab "\t" separated values, all values are in decimal and in one line without other characters.
   */
  tab_separated_values = "tab_separated_values",

  /**
   * Newline (\n) separated values, all values are in decimal and one per line with a terminating newline.
   */
  newline_separated_values = "newline_separated_values",

  /**
   * A JSON file in the format "[1,2,3,4...]"
   */
  json_array = "json_array",
}

export type SerializationFormatType =
  | SerializationFormat
  | "croaring"
  | "portable"
  | "unsafe_frozen_croaring"
  | "uint32_array"
  | boolean;

export type FileSerializationFormatType =
  | SerializationFormatType
  | FileSerializationFormat
  | "comma_separated_values"
  | "tab_separated_values"
  | "newline_separated_values"
  | "json_array";

export type SerializationDeserializationFormatType = SerializationFormatType & DeserializationFormatType;

export type FileSerializationDeserializationFormatType = FileSerializationFormatType & FileDeserializationFormatType;

export enum DeserializationFormat {
  /** Stable Optimized non portable C/C++ format. Used by croaring. Can be smaller than the portable format. */
  croaring = "croaring",

  /** Stable Portable Java and Go format. */
  portable = "portable",

  /**
   * Non portable C/C++ frozen format.
   * Is considered unsafe and unstable because the format might change at any new version.
   * Can be useful for temporary storage or for sending data over the network between similar machines.
   * If the content is corrupted when loaded or the buffer is modified when a frozen view is create, the behavior is undefined!
   * The application may crash, buffer overrun, could be a vector of attack!
   */
  unsafe_frozen_croaring = "unsafe_frozen_croaring",

  /**
   * Portable version of the frozen view, compatible with Go and Java.
   * Is considered unsafe and unstable because the format might change at any new version.
   * Can be useful for temporary storage or for sending data over the network between similar machines.
   * If the content is corrupted when loaded or the buffer is modified when a frozen view is create, the behavior is undefined!
   * The application may crash, buffer overrun, could be a vector of attack!
   */
  unsafe_frozen_portable = "unsafe_frozen_portable",

  /**
   * A plain binary array of 32 bits integers in little endian format. 4 bytes per value.
   */
  uint32_array = "uint32_array",

  comma_separated_values = "comma_separated_values",
  tab_separated_values = "tab_separated_values",
  newline_separated_values = "newline_separated_values",
  json_array = "json_array",
}

export type DeserializationFormatType =
  | DeserializationFormat
  | "croaring"
  | "portable"
  | "unsafe_frozen_croaring"
  | "unsafe_frozen_portable"
  | "uint32_array"
  | "comma_separated_values"
  | "tab_separated_values"
  | "newline_separated_values"
  | "json_array"
  | boolean;

export enum FileDeserializationFormat {
  /** Stable Optimized non portable C/C++ format. Used by croaring. Can be smaller than the portable format. */
  croaring = "croaring",

  /** Stable Portable Java and Go format. */
  portable = "portable",

  /**
   * Non portable C/C++ frozen format.
   * Is considered unsafe and unstable because the format might change at any new version.
   * Can be useful for temporary storage or for sending data over the network between similar machines.
   * If the content is corrupted when loaded or the buffer is modified when a frozen view is create, the behavior is undefined!
   * The application may crash, buffer overrun, could be a vector of attack!
   */
  unsafe_frozen_croaring = "unsafe_frozen_croaring",

  /**
   * Portable version of the frozen view, compatible with Go and Java.
   * Is considered unsafe and unstable because the format might change at any new version.
   * Can be useful for temporary storage or for sending data over the network between similar machines.
   * If the content is corrupted when loaded or the buffer is modified when a frozen view is create, the behavior is undefined!
   * The application may crash, buffer overrun, could be a vector of attack!
   */
  unsafe_frozen_portable = "unsafe_frozen_portable",

  /**
   * A plain binary array of 32 bits integers in little endian format. 4 bytes per value.
   */
  uint32_array = "uint32_array",

  comma_separated_values = "comma_separated_values",
  tab_separated_values = "tab_separated_values",
  newline_separated_values = "newline_separated_values",
  json_array = "json_array",
}

export type FileDeserializationFormatType = DeserializationFormatType | FileDeserializationFormat;

export enum FrozenViewFormat {
  /**
   * Non portable C/C++ frozen format.
   * Is considered unsafe and unstable because the format might change at any new version.
   * Can be useful for temporary storage or for sending data over the network between similar machines.
   * If the content is corrupted when loaded or the buffer is modified when a frozen view is create, the behavior is undefined!
   * The application may crash, buffer overrun, could be a vector of attack!
   */
  unsafe_frozen_croaring = "unsafe_frozen_croaring",

  /**
   * Portable version of the frozen view, compatible with Go and Java.
   * Is considered unsafe and unstable because the format might change at any new version.
   * Can be useful for temporary storage or for sending data over the network between similar machines.
   * If the content is corrupted when loaded or the buffer is modified when a frozen view is create, the behavior is undefined!
   * The application may crash, buffer overrun, could be a vector of attack!
   */
  unsafe_frozen_portable = "unsafe_frozen_portable",
}

export type FrozenViewFormatType = FrozenViewFormat | "unsafe_frozen_croaring" | "unsafe_frozen_portable";

export interface ReadonlyRoaringBitmap32
  extends Omit<ReadonlySet<number>, "forEach" | "keys" | "values" | "entries" | typeof Symbol.iterator> {
  /**
   * Property. Gets the number of items in the set (cardinality).
   *
   * @type {number}
   * @memberof ReadonlyRoaringBitmap32
   */
  get size(): number;

  /**
   * Property. True if the bitmap is empty.
   *
   * @type {boolean}
   * @memberof ReadonlyRoaringBitmap32
   */
  get isEmpty(): boolean;

  /**
   * Property. True if the bitmap is read-only.
   * A read-only bitmap cannot be modified, every operation will throw an error.
   * You can freeze a bitmap using the freeze() method.
   * A bitmap cannot be unfrozen.
   *
   * @type {boolean}
   * @memberof ReadonlyRoaringBitmap32
   */
  get isFrozen(): boolean;

  /**
   * [Symbol.iterator]() Gets a new iterator able to iterate all values in the set in ascending order.
   *
   * WARNING: Is not allowed to change the bitmap while iterating.
   * The iterator may throw exception if the bitmap is changed during the iteration.
   *
   * @returns {RoaringBitmap32Iterator} A new iterator
   * @memberof ReadonlyRoaringBitmap32
   */
  [Symbol.iterator](): RoaringBitmap32Iterator;

  /**
   * Gets a new iterator able to iterate all values in the set in ascending order.
   *
   * WARNING: Is not allowed to change the bitmap while iterating.
   * The iterator may throw exception if the bitmap is changed during the iteration.
   *
   * Same as [Symbol.iterator]()
   *
   * @returns {RoaringBitmap32Iterator} A new iterator
   * @memberof ReadonlyRoaringBitmap32
   */
  iterator(): RoaringBitmap32Iterator;

  /**
   * Gets a new iterator able to iterate all values in the set in descending order.
   *
   * WARNING: Is not allowed to change the bitmap while iterating.
   * The iterator may throw exception if the bitmap is changed during the iteration.
   *
   * @returns {RoaringBitmap32Iterator} A new reverse iterator
   * @memberof ReadonlyRoaringBitmap32
   */
  reverseIterator(): RoaringBitmap32Iterator;

  /**
   * Gets a new iterator able to iterate all values in the set in ascending order.
   * This is just for compatibility with the Set<number> interface.
   *
   * WARNING: Is not allowed to change the bitmap while iterating. Undefined behaviour.
   * The iterator may throw exception if the bitmap is changed during the iteration.
   *
   * Same as [Symbol.iterator]()
   *
   * @returns {RoaringBitmap32Iterator} A new iterator
   * @memberof ReadonlyRoaringBitmap32
   */
  keys(): RoaringBitmap32Iterator;

  /**
   * Gets a new iterator able to iterate all values in the set in ascending order.
   * This is just for compatibility with the Set<number> interface.
   *
   * WARNING: Is not allowed to change the bitmap while iterating. Undefined behaviour.
   * The iterator may throw exception if the bitmap is changed during the iteration.
   *
   * Same as [Symbol.iterator]()
   *
   * @returns {RoaringBitmap32Iterator} A new iterator
   * @memberof ReadonlyRoaringBitmap32
   */
  values(): RoaringBitmap32Iterator;

  /**
   * Gets a new iterator able to iterate all value pairs [value, value] in the set in ascending order.
   * This is just for compatibility with the Set<number> interface.
   *
   * WARNING: Is not allowed to change the bitmap while iterating. Undefined behaviour.
   * The iterator may throw exception if the bitmap is changed during the iteration.
   *
   * Same as [Symbol.iterator]()
   *
   * @returns {RoaringBitmap32Iterator} A new iterator
   * @memberof ReadonlyRoaringBitmap32
   */
  entries(): ReturnType<Set<number>["entries"]>;

  /**
   * Executes a function for each value in the set, in ascending order.
   * The callback has 3 arguments, the value, the value and this (this set). This is to match the Set<number> interface.
   *
   * WARNING: Is not allowed to change the bitmap while iterating. Undefined behaviour.
   *
   * WARNING: the second parameter of the callback is not the index, but the value itself, the same as the first argument.
   * This is required to match the Set<number> interface.
   */
  forEach<This = unknown>(
    callbackfn: (this: This, value: number, index: number, set: this) => void,
    thisArg?: This,
  ): this;

  /**
   * Behaves like array.some.
   * The some() method tests whether at least one element in the set passes the test implemented by the provided function.
   * It returns true if, in the set, it finds an element for which the provided function returns true; otherwise it returns false.
   *
   * WARNING: this can potentially iterate a large set of to 4 billion elements.
   *
   * WARNING: Is not allowed to change the bitmap while iterating. Undefined behaviour.
   *
   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some
   */
  some(callbackfn: (value: number, index: number, set: this) => boolean, thisArg?: unknown): boolean;

  /**
   * Behaves like array.every.
   * The every() method tests whether all elements in the set pass the test implemented by the provided function.
   * It returns a Boolean value.
   *
   * WARNING: this can potentially iterate a large set of to 4 billion elements.
   *
   * WARNING: Is not allowed to change the bitmap while iterating. Undefined behaviour.
   *
   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every
   */
  every(callbackfn: (value: number, index: number, set: this) => boolean, thisArg?: unknown): boolean;

  /**
   * Behaves like array.reduce.
   * The reduce() method applies a function against an accumulator and each value of the set (from left-to-right) to reduce it to a single value.
   *
   * WARNING: this can potentially iterate a large set of to 4 billion elements.
   *
   * WARNING: Is not allowed to change the bitmap while iterating. Undefined behaviour.
   *
   * @param callbackfn A function that accepts up to four arguments. The reduce method calls the callbackfn function one time for each element in the set.
   * @returns The value that results from the reduction.
   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce
   * @memberof ReadonlyRoaringBitmap32
   */
  reduce(callbackfn: (previousValue: number, currentValue: number, currentIndex: number, set: this) => number): number;
  reduce(
    callbackfn: (previousValue: number, currentValue: number, currentIndex: number, set: this) => number,
    initialValue: number | undefined,
  ): number;
  reduce<U>(
    callbackfn: (previousValue: U, currentValue: number, currentIndex: number, set: this) => U,
    initialValue: U,
  ): U;

  /**
   * Behaves like array.reduceRight.
   * The reduceRight() method applies a function against an accumulator and each value of the set (from right-to-left) to reduce it to a single value.
   * WARNING: this can potentially iterate a large set of to 4 billion elements.
   * WARNING: Is not allowed to change the bitmap while iterating. Undefined behaviour.
   * @param callbackfn A function that accepts up to four arguments. The reduce method calls the callbackfn function one time for each element in the set.
   * @returns The value that results from the reduction.
   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduceRight
   * @memberof ReadonlyRoaringBitmap32
   */
  reduceRight(
    callbackfn: (previousValue: number, currentValue: number, currentIndex: number, set: this) => number,
  ): number;
  reduceRight(
    callbackfn: (previousValue: number, currentValue: number, currentIndex: number, set: this) => number,
    initialValue: number | undefined,
  ): number;
  reduceRight<U>(
    callbackfn: (previousValue: U, currentValue: number, currentIndex: number, set: this) => U,
    initialValue: U,
  ): U;

  /**
   * Behaves like array.find.
   * The find() method returns the value of the first element in the set that satisfies the provided testing function.
   * Otherwise undefined is returned.
   * WARNING: this can potentially iterate a large set of to 4 billion elements.
   * WARNING: Is not allowed to change the bitmap while iterating. Undefined behaviour.
   * @param predicate find calls predicate once for each element of the set, in ascending order, until it finds one where predicate returns true.
   * If such an element is found, find immediately returns that element value. Otherwise, find returns undefined.
   * @param thisArg If provided, it will be used as the this value for each invocation of predicate.
   * If it is not provided, undefined is used instead.
   * @returns The value of the first element in the set that satisfies the provided testing function.
   * Otherwise undefined is returned.
   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find
   * @memberof ReadonlyRoaringBitmap32
   */
  find(predicate: (value: number, index: number, set: this) => boolean, thisArg?: unknown): number | undefined;

  /**
   * Behaves like array.findIndex.
   * The findIndex() method returns the index of the first element in the set that satisfies the provided testing function.
   * Otherwise, it returns -1, indicating that no element passed the test.
   * WARNING: this can potentially iterate a large set of to 4 billion elements.
   * WARNING: Is not allowed to change the bitmap while iterating. Undefined behaviour.
   * @param predicate find calls predicate once for each element of the set, in ascending order, until it finds one where predicate returns true.
   * If such an element is found, findIndex immediately returns that element index. Otherwise, findIndex returns -1.
   * @param thisArg If provided, it will be used as the this value for each invocation of predicate.
   * If it is not provided, undefined is used instead.
   * @returns The index of the first element in the set that satisfies the provided testing function.
   * Otherwise, it returns -1, indicating that no element passed the test.
   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex
   * @memberof ReadonlyRoaringBitmap32
   */
  findIndex(predicate: (value: number, index: number, set: this) => boolean, thisArg?: unknown): number;

  /**
   * It behaves like array.map.
   * WARNING: The returned array may be very big, up to 4 billion elements.
   * WARNING: Is not allowed to change the bitmap while iterating. Undefined behaviour.
   *
   * @param callbackfn A function that accepts up to three arguments. The map method calls the callbackfn function one time for each element in the array.
   * @param thisArg An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.
   * @returns An array containing the results of calling the callbackfn function on each element in the set.
   * @memberof ReadonlyRoaringBitmap32
   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map
   */
  map<U, This = unknown>(
    callbackfn: (this: This, value: number, index: number, set: this) => U,
    thisArg?: This,
    output?: U[],
  ): U[];

  /**
   * It behaves like array.filter.
   * WARNING: The returned array may be very big, up to 4 billion elements.
   * WARNING: Is not allowed to change the bitmap while iterating. Undefined behaviour.
   *
   * @param callbackfn A function that accepts up to three arguments. The filter method calls the callbackfn function one time for each element in the array.
   * @param thisArg An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.
   * @returns A new array containing all elements of the array that satisfy the given predicate.
   * @memberof ReadonlyRoaringBitmap32
   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter
   */
  filter(
    predicate: (value: number, index: number, set: this) => boolean,
    thisArg?: unknown,
    output?: number[],
  ): number[];

  /**
   * It behaves like array.toSorted.
   * Returns a new array that is this set sorted according to the compare function.
   * If no sorting function is provided, the array is sorted according to the numeric order of the values (the same as calling this.toArray()).
   *
   * WARNING: The returned array may be very big, up to 4 billion elements.
   * WARNING: Is not allowed to change the bitmap while iterating. Undefined behaviour.
   *
   * @param cmp A function that defines an alternative sort order. The sort method calls the compareFunction function
   * once for each element in the array.
   * @returns A new sorted array that contains all the elements of this set.
   * @memberof ReadonlyRoaringBitmap32
   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toSorted
   */
  toSorted(cmp?: (a: number, b: number) => number): number[];

  /**
   * It behaves like array.toReversed.
   * Returns a new array that is this set sorted in reverse order.
   * WARNING: The returned array may be very big, up to 4 billion elements.
   * @returns An array containing the elements of this set in reverse order (descending).
   */
  toReversed(): number[];

  /**
   * Gets the minimum value in the set.
   *
   * @returns {number} The minimum value in the set or 0xFFFFFFFF if empty.
   * @memberof ReadonlyRoaringBitmap32
   */
  minimum(): number;

  /**
   * Gets the maximum value in the set.
   *
   * @returns {number} The minimum value in the set or 0 if empty.
   * @memberof ReadonlyRoaringBitmap32
   */
  maximum(): number;

  /**
   * Checks wether the given value exists in the set.
   * Is the same as this.includes(value).
   *
   * @param {number} value A 32 bit unsigned integer to search.
   * @returns {boolean} True if the set contains the given value, false if not.
   * @memberof ReadonlyRoaringBitmap32
   */
  has(value: unknown): boolean;

  /**
   * Checks wether the given value exists in the set.
   * Is the same as this.has(value).
   *
   * @param {number} value A 32 bit unsigned integer to search.
   * @returns {boolean} True if the set contains the given value, false if not.
   * @memberof ReadonlyRoaringBitmap32
   */
  includes(value: unknown): boolean;

  /**
   * Returns the index of value in the set, index start from 0.
   * If the set doesn't contain value, this function will return -1.
   * The difference with rank function is that this function will return -1 when value isn't in the set, but the rank function will return a non-negative number.
   *
   * @param {number} value A 32 bit unsigned integer to search.
   * @param {number} [fromIndex] The index to start the search at, defaults to 0. It does not have performance difference, is just for compatibility with array.indexOf.
   * @returns {boolean} True if the set contains the given value, false if not.
   * @memberof ReadonlyRoaringBitmap32
   */
  indexOf(value: unknown, fromIndex?: number): number;

  /**
   * Returns the index of value in the set, index start from 0.
   * If the set doesn't contain value, this function will return -1.
   * The difference with rank function is that this function will return -1 when value isn't in the set, but the rank function will return a non-negative number.
   * If fromIndex is not specified, is the same as this.indexOf(value).
   * It behaves like array.lastIndexOf, but it doesn't have performance difference, is just for compatibility with array.lastIndexOf.
   *
   * @param {number} value A 32 bit unsigned integer to search.
   * @param {number} [fromIndex] The index to start the search at, defaults to 0. It does not have performance difference, is just for compatibility with array.indexOf.
   * @returns {boolean} True if the set contains the given value, false if not.
   * @memberof ReadonlyRoaringBitmap32
   */
  lastIndexOf(value: unknown, fromIndex?: number): number;

  /**
   * Check whether a range of values from rangeStart (included) to rangeEnd (excluded) is present
   *
   * @param {number|undefined} rangeStart The start index (inclusive).
   * @param {number|undefined} [rangeEnd] The end index (exclusive).
   * @returns {boolean} True if the bitmap contains the whole range of values from rangeStart (included) to rangeEnd (excluded), false if not.
   * @memberof ReadonlyRoaringBitmap32
   */
  hasRange(rangeStart: number | undefined, rangeEnd?: number | undefined): boolean;

  /**
   * Gets the cardinality (number of elements) between rangeStart (included) to rangeEnd (excluded) of the bitmap.
   * Returns 0 if range is invalid or if no element was found in the given range.
   *
   * @param {number|undefined} rangeStart The start index (inclusive).
   * @param {number|undefined} [rangeEnd] The end index (exclusive).
   * @returns {number} The number of elements between rangeStart (included) to rangeEnd (excluded).
   */
  rangeCardinality(rangeStart: number | undefined, rangeEnd?: number | undefined): number;

  /**
   * Checks wether this set is a subset or the same as the given set.
   *
   * Returns false also if the given argument is not a ReadonlyRoaringBitmap32 instance.
   *
   * @param {ReadonlyRoaringBitmap32} other The other set.
   * @returns {boolean} True if this set is a subset of the given ReadonlyRoaringBitmap32. False if not.
   * @memberof ReadonlyRoaringBitmap32
   */
  isSubset(other: ReadonlyRoaringBitmap32): boolean;

  /**
   * Checks wether this set is a superset or the same as the given set.
   *
   * Returns false also if the given argument is not a ReadonlyRoaringBitmap32 instance.
   *
   * @param {ReadonlyRoaringBitmap32} other The other set.
   * @returns {boolean} True if this set is a superset of the given ReadonlyRoaringBitmap32. False if not.
   * @memberof ReadonlyRoaringBitmap32
   */
  isSuperset(other: ReadonlyRoaringBitmap32): boolean;

  /**
   * Checks wether this set is a strict subset of the given set.
   *
   * Returns false if the sets are the same.
   *
   * Returns false also if the given argument is not a ReadonlyRoaringBitmap32 instance.
   *
   * @param {ReadonlyRoaringBitmap32} other The other ReadonlyRoaringBitmap32 instance.
   * @returns {boolean} True if this set is a strict subset of the given ReadonlyRoaringBitmap32. False if not.
   * @memberof ReadonlyRoaringBitmap32
   */
  isStrictSubset(other: ReadonlyRoaringBitmap32): boolean;

  /**
   * Checks wether this set is a strict superset of the given set.
   *
   * Returns false if the sets are the same.
   *
   * Returns false also if the given argument is not a ReadonlyRoaringBitmap32 instance.
   *
   * @param {ReadonlyRoaringBitmap32} other The other ReadonlyRoaringBitmap32 instance.
   * @returns {boolean} True if this set is a strict superset of the given ReadonlyRoaringBitmap32. False if not.
   * @memberof ReadonlyRoaringBitmap32
   */
  isStrictSuperset(other: ReadonlyRoaringBitmap32): boolean;

  /**
   * Checks wether this set is equal to another set.
   *
   * Returns false also if the given argument is not a ReadonlyRoaringBitmap32 instance.
   *
   * @param {ReadonlyRoaringBitmap32} other The other set to compare for equality.
   * @returns {boolean} True if the two sets contains the same elements, false if not.
   * @memberof ReadonlyRoaringBitmap32
   */
  isEqual(other: ReadonlyRoaringBitmap32): boolean;

  /**
   * Check whether the two bitmaps intersect.
   *
   * Returns true if there is at least one item in common, false if not.
   *
   * Returns false also if the given argument is not a ReadonlyRoaringBitmap32 instance.
   *
   * @param {ReadonlyRoaringBitmap32} other The other set to compare for intersection.
   * @returns {boolean}  True if the two set intersects, false if not.
   * @memberof ReadonlyRoaringBitmap32
   */
  intersects(other: ReadonlyRoaringBitmap32): boolean;

  /**
   * Check whether a bitmap and a closed range intersect.
   *
   * @param {number|undefined} rangeStart The start of the range.
   * @param {number|undefined} [rangeEnd] The end of the range.
   * @returns {boolean} True if the bitmap and the range intersects, false if not.
   */
  intersectsWithRange(rangeStart: number | undefined, rangeEnd?: number | undefined): boolean;

  /**
   * Computes the size of the intersection between two bitmaps (the number of values in common).
   *
   * Returns -1 if the given argument is not a ReadonlyRoaringBitmap32 instance.
   *
   * @param {ReadonlyRoaringBitmap32} other The other set to compare for intersection.
   * @returns {number} The number of elements in common.
   * @memberof ReadonlyRoaringBitmap32
   */
  andCardinality(other: ReadonlyRoaringBitmap32): number;

  /**
   * Computes the size of the union between two bitmaps.
   *
   * Returns -1 if the given argument is not a ReadonlyRoaringBitmap32 instance.
   *
   * @param {ReadonlyRoaringBitmap32} other The other set to compare for intersection.
   * @returns {number} The number of elements in common.
   * @memberof ReadonlyRoaringBitmap32
   */
  orCardinality(other: ReadonlyRoaringBitmap32): number;

  /**
   * Computes the size of the difference (andnot) between two bitmaps.
   *
   * Returns -1 if the given argument is not a ReadonlyRoaringBitmap32 instance.
   *
   * @param {ReadonlyRoaringBitmap32} other The other set to compare for intersection.
   * @returns {number}  The number of elements in common.
   * @memberof ReadonlyRoaringBitmap32
   */
  andNotCardinality(other: ReadonlyRoaringBitmap32): number;

  /**
   * Computes the size of the symmetric difference (xor) between two bitmaps.
   *
   * Returns -1 if the given argument is not a ReadonlyRoaringBitmap32 instance.
   *
   * @param {ReadonlyRoaringBitmap32} other The other set to compare for intersection.
   * @returns {number} The number of elements in common.
   * @memberof ReadonlyRoaringBitmap32
   */
  xorCardinality(other: ReadonlyRoaringBitmap32): number;

  /**
   * Computes the Jaccard index between two bitmaps.
   * (Also known as the Tanimoto distance or the Jaccard similarity coefficient).
   *
   * See https://en.wikipedia.org/wiki/Jaccard_index
   *
   * The Jaccard index is undefined if both bitmaps are empty.
   *
   * Returns -1 if the given argument is not a ReadonlyRoaringBitmap32 instance.
   *
   * @param {ReadonlyRoaringBitmap32} other The other ReadonlyRoaringBitmap32 to compare.
   * @returns {number} The Jaccard index.
   * @memberof ReadonlyRoaringBitmap32
   */
  jaccardIndex(other: ReadonlyRoaringBitmap32): number;

  /**
   *  Returns the number of values in the set that are smaller or equal to the given value.
   *
   * @param {number} maxValue The maximum value
   * @returns {number} Returns the number of values in the set that are smaller or equal to the given value.
   * @memberof ReadonlyRoaringBitmap32
   */
  rank(maxValue: number): number;

  /**
   * If the size of the roaring bitmap is strictly greater than rank,
   * then this function returns the element of given rank.
   *
   * Otherwise, it returns undefined.
   *
   * @param {number} rank The rank, an unsigned 32 bit integer.
   * @returns {(number | undefined)} The element of the given rank or undefined if not found.
   * @memberof ReadonlyRoaringBitmap32
   */
  select(rank: number): number | undefined;

  /**
   * Creates a new Uint32Array and fills it with all the values in the bitmap.
   *
   * The returned array may be very big, up to 4 billion elements.
   *
   * Use this function only when you know what you are doing.
   *
   * This function is faster than calling new Uint32Array(bitmap);
   *
   * See rangeUint32Array to paginate.
   *
   * @returns A new Uint32Array instance containing all the items in the set in order.
   * @memberof ReadonlyRoaringBitmap32
   */
  toUint32Array(): Uint32Array;

  /**
   * Creates a new Uint32Array and fills it with all the values in the bitmap up to the given length.
   *
   * See rangeUint32Array to paginate.
   *
   * @returns A new Uint32Array instance containing all the items in the set in order.
   * @memberof ReadonlyRoaringBitmap32
   */
  toUint32Array(maxSize: number): Uint32Array;

  /**
   * Copies all the values in the roaring bitmap to an Uint32Array.
   *
   * This function is faster than calling new Uint32Array(bitmap);
   * Throws if the given array is not a valid Uint32Array or Int32Array or is not big enough.
   *
   * See rangeUint32Array to paginate.
   *
   * @param {TOutput} output The output array.
   * @returns {Uint32Array} The output array. Limited to the resulting size.
   * @memberof ReadonlyRoaringBitmap32
   */
  toUint32Array(output: Uint32Array | Int32Array | ArrayBuffer | SharedArrayBuffer): Uint32Array;

  /**
   * Creates a new Uint32Array and fills it with all the values in the bitmap, asynchronously.
   * The bitmap will be temporarily frozen until the operation completes.
   *
   * The returned array may be very big, up to 4 billion elements.
   *
   * Use this function only when you know what you are doing.
   *
   * This function is faster than calling new Uint32Array(bitmap);
   *
   * See rangeUint32Array to paginate.
   *
   * @returns A new Uint32Array instance containing all the items in the set in order.
   * @memberof ReadonlyRoaringBitmap32
   */
  toUint32ArrayAsync(): Promise<Uint32Array>;

  /**
   * Copies all the values in the roaring bitmap to an Uint32Array, asynchronously.
   * The bitmap will be temporarily frozen until the operation completes.
   *
   * This function is faster than calling new Uint32Array(bitmap);
   * Throws if the given array is not a valid Uint32Array or Int32Array or is not big enough.
   *
   * See rangeUint32Array to paginate.
   *
   * @param {TOutput} output The output array.
   * @returns {Uint32Array} The output array. Limited to the resulting size.
   * @memberof ReadonlyRoaringBitmap32
   */
  toUint32ArrayAsync(output: Uint32Array | Int32Array | ArrayBuffer | SharedArrayBuffer): Promise<Uint32Array>;

  /**
   * toUint32Array array with pagination
   * @returns A new Uint32Array instance containing paginated items in the set in order.
   * @memberof ReadonlyRoaringBitmap32
   */
  rangeUint32Array(
    output: Uint32Array | Int32Array | ArrayBuffer | SharedArrayBuffer,
    offset: number,
    limit?: number | undefined,
  ): Uint32Array;

  /**
   * toUint32Array array with pagination
   * @returns A new Uint32Array instance containing paginated items in the set in order.
   * @memberof ReadonlyRoaringBitmap32
   */
  rangeUint32Array(minimumValue: number, maximumValue: number): Uint32Array;

  /**
   * toUint32Array array with pagination
   * @param {TOutput} output The output array.
   * @returns {Uint32Array} The output array. Limited to the resulting size.
   * @memberof ReadonlyRoaringBitmap32
   */
  rangeUint32Array(
    minimumValue: number,
    maximumValue: number,
    output: Uint32Array | Int32Array | ArrayBuffer | SharedArrayBuffer,
  ): Uint32Array;

  /**
   * toUint32Array array with pagination
   * @param {TOutput} output The output array.
   * @returns {Uint32Array} The output array. Limited to the resulting size.
   * @memberof ReadonlyRoaringBitmap32
   */
  rangeUint32Array(
    minimumValue: number,
    output: Uint32Array | Int32Array | ArrayBuffer | SharedArrayBuffer,
  ): Uint32Array;

  /**
   * Same as toUint32Array
   * @param {TOutput} output The output array.
   * @returns {Uint32Array} The output array. Limited to the resulting size.
   * @memberof ReadonlyRoaringBitmap32
   */
  rangeUint32Array(output: Uint32Array | Int32Array | ArrayBuffer | SharedArrayBuffer): Uint32Array;

  /**
   * Creates a new plain JS array and fills it with all the values in the bitmap.
   *
   * The returned array may be very big, use this function only when you know what you are doing.
   *
   * @param {number} [maxLength] The maximum number of elements to return.
   * @returns {number[]}  A new plain JS array that contains all the items in the set in order.
   * @memberof ReadonlyRoaringBitmap32
   */
  toArray(maxLength?: number | undefined): number[];

  /**
   * Append all the values in this bitmap to the given plain JS array.
   *
   * The resulting array may be very big, use this function only when you know what you are doing.
   *
   * @template TOutput The type of the output array.
   * @param {TOutput} output The output array.
   * @param {number} [maxLength] The maximum number of elements to return.
   * @returns {TOutput} The output array.
   * @memberof ReadonlyRoaringBitmap32
   */
  toArray<TOutput extends number[]>(output: TOutput, maxLength?: number, offset?: number): TOutput;

  /**
   * Creates a new plain JS Set<number> and fills it with all the values in the bitmap.
   *
   * The returned set may be very big, use this function only when you know what you are doing.
   *
   * @param {number} [maxLength] The maximum number of elements to return.
   * @returns {Set<number>} A new plain JS array that contains all the items in the set in order.
   * @memberof ReadonlyRoaringBitmap32
   */
  toSet(maxLength?: number | undefined): Set<number>;

  /**
   * Adds all the values in this bitmap to the given plain JS Set<number>.
   *
   * The resulting set may be very big, use this function only when you know what you are doing.
   *
   * @param {Set<number>} output The output set.
   * @param {number} [maxLength] The maximum number of elements to return.
   * @returns {Set<number>} The output set.
   * @memberof ReadonlyRoaringBitmap32
   */
  toSet(output: Set<number>, maxLength?: number | undefined): Set<number>;

  /**
   * Returns a plain JS array with all the values in the bitmap.
   *
   * Used by JSON.stringify to serialize this bitmap as an array.
   *
   * @returns {number[]} A new plain JS array that contains all the items in the set in order.
   * @memberof ReadonlyRoaringBitmap32
   */
  toJSON(): number[];

  /**
   * How many bytes are required to serialize this bitmap.
   *
   * Setting the format flag to false enable a custom format that can save space compared to the portable format (e.g., for very sparse bitmaps).
   * The portable version is meant to be compatible with Java and Go versions.
   *
   * @param {SerializationFormat | boolean} format One of the SerializationFormat enum values, or a boolean value: if false, optimized C/C++ format is used. If true, Java and Go portable format is used.
   * @returns {number} How many bytes are required to serialize this bitmap.
   * @memberof ReadonlyRoaringBitmap32
   */
  getSerializationSizeInBytes(format: SerializationFormatType): number;

  /**
   * Serializes the bitmap into a new Buffer.
   *
   * Setting the formatg to false enable a custom format that can save space compared to the portable format (e.g., for very sparse bitmaps).
   * The portable version is meant to be compatible with Java and Go versions.
   *
   * @param {SerializationFormat | boolean} format One of the SerializationFormat enum values, or a boolean value: if false, optimized C/C++ format is used. If true, Java and Go portable format is used.
   * @returns {Buffer} A new node Buffer that contains the serialized bitmap.
   * @memberof ReadonlyRoaringBitmap32
   */
  serialize(format: SerializationFormatType, _output?: undefined): Buffer;

  /**
   * Serializes the bitmap into the given Buffer, starting to write at the given outputStartIndex position.
   * The operation will fail with an error if the buffer is smaller than what getSerializationSizeInBytes(format) returns.
   *
   * Setting the format to false enable a custom format that can save space compared to the portable format (e.g., for very sparse bitmaps).
   * The portable version is meant to be compatible with Java and Go versions.
   *
   * @param {boolean} format If false, optimized C/C++ format is used. If true, Java and Go portable format is used.
   * @param {Buffer} output The node Buffer where to write the serialized data.
   * @returns {Buffer} The output Buffer. If the input buffer was exactly of the same size. Otherwise, a new buffer backed by the same storage is returned, with the correct offset and length.
   * @memberof ReadonlyRoaringBitmap32
   */
  serialize(
    format: SerializationFormatType,
    output: Uint8Array | Int8Array | Uint8ClampedArray | ArrayBuffer | SharedArrayBuffer,
  ): Buffer;

  /**
   * Serializes the bitmap into the given Buffer, starting to write at position 0.
   * The operation will fail with an error if the buffer is smaller than what getSerializationSizeInBytes(format) returns.
   *
   * Setting the portable flag to false enable a custom format that can save space compared to the portable format (e.g., for very sparse bitmaps).
   * The portable version is meant to be compatible with Java and Go versions.
   *
   * @param {boolean} portable If false, optimized C/C++ format is used. If true, Java and Go portable format is used.
   * @param {Buffer} output The node Buffer where to write the serialized data.
   * @returns {Buffer} The output Buffer. If the input buffer was exactly of the same size. Otherwise, a new buffer backed by the same storage is returned, with the correct offset and length.
   * @memberof ReadonlyRoaringBitmap32
   */
  serialize(
    output: Uint8Array | Int8Array | Uint8ClampedArray | ArrayBuffer | SharedArrayBuffer,
    format: SerializationFormatType,
  ): Buffer;

  /**
   * Serializes the bitmap into a new Buffer.
   * The bitmap will be temporarily frozen until the operation completes.
   *
   * Setting the portable flag to false enable a custom format that can save space compared to the portable format (e.g., for very sparse bitmaps).
   * The portable version is meant to be compatible with Java and Go versions.
   *
   * @param {SerializationFormat | boolean} format One of the SerializationFormat enum values, or a boolean value: if false, optimized C/C++ format is used. If true, Java and Go portable format is used.
   * @returns {Buffer} A new node Buffer that contains the serialized bitmap.
   * @memberof ReadonlyRoaringBitmap32
   */
  serializeAsync(format: SerializationFormatType, _output?: undefined): Promise<Buffer>;

  /**
   * Serializes the bitmap into the given Buffer, starting to write at the given outputStartIndex position.
   * The bitmap will be temporarily frozen until the operation completes.
   * The operation will fail with an error if the buffer is smaller than what getSerializationSizeInBytes(format) returns.
   *
   * Setting the portable flag to false enable a custom format that can save space compared to the portable format (e.g., for very sparse bitmaps).
   * The portable version is meant to be compatible with Java and Go versions.
   *
   * @param {boolean} format If false, optimized C/C++ format is used. If true, Java and Go portable format is used.
   * @param {Buffer} output The node Buffer where to write the serialized data.
   * @returns {Promise<Buffer>} The output Buffer. If the input buffer was exactly of the same size, the same buffer is returned. Otherwise, a new buffer backed by the same storage is returned, with the correct offset and length.
   * @memberof ReadonlyRoaringBitmap32
   */
  serializeAsync(
    format: SerializationFormatType,
    output: Uint8Array | Int8Array | Uint8ClampedArray | ArrayBuffer | SharedArrayBuffer,
  ): Promise<Buffer>;

  /**
   * Serializes the bitmap into the given Buffer, starting to write at position 0.
   * The bitmap will be temporarily frozen until the operation completes.
   * The operation will fail with an error if the buffer is smaller than what getSerializationSizeInBytes(format) returns.
   *
   * Setting the portable flag to false enable a custom format that can save space compared to the portable format (e.g.,