tiny-ulid/default.d.ts

Make and decode ULIDs.

import type { Brand, LaxPartial } from "@samual/types";
/** A 16-byte {@linkcode ArrayBuffer}. */
export type UlidBuffer = Brand<ArrayBuffer, {
	readonly UlidBuffer: unique symbol;
}[`UlidBuffer`]>;
export type UlidBytes = Brand<Uint8Array<UlidBuffer>, {
	readonly UlidBytes: unique symbol;
}[`UlidBytes`]>;
/** A valid [ULID](https://github.com/ulid/spec#readme) string. */
export type Ulid = Brand<string, {
	readonly Ulid: unique symbol;
}[`Ulid`]>;
/** Check if the given {@linkcode ArrayBuffer}'s length is 16, if so narrow it to a {@linkcode UlidBuffer}. */
export declare const isUlidBuffer: (arrayBuffer: ArrayBuffer) => arrayBuffer is UlidBuffer;
/** If the {@linkcode ArrayBuffer} has a length of 16, it'll be returned as a {@linkcode UlidBuffer}, otherwise throws. */
export declare const toUlidBuffer: (arrayBuffer: ArrayBuffer) => UlidBuffer;
export declare const isUlidBytes: (bytes: Uint8Array) => bytes is UlidBytes;
export declare const toUlidBytes: (bytes: UlidBytes) => UlidBytes;
export declare const ulidBufferToBytes: (ulidBuffer: UlidBuffer) => UlidBytes;
/** Check if the given string is a valid [ULID](https://github.com/ulid/spec#readme), if so narrow it to a {@linkcode Ulid}. */
export declare const isUlid: (string: string) => string is Ulid;
/** If the string is a valid [ULID](https://github.com/ulid/spec#readme), it'll be returned as a `Ulid`, otherwise throws. */
export declare const toUlid: (string: string) => Ulid;
/**
* Make an empty 16-byte {@linkcode ArrayBuffer} that's narrowed to a {@linkcode UlidBuffer}.
*
* This can be useful if you don't want to use {@linkcode makeUlid()} or {@linkcode makeUlidBuffer()} to for example use
* a custom random function.
* @example
* ```js
* const ulidBuffer = makeEmptyUlidBuffer()
*
* setUlidBufferTime(ulidBuffer, 1469922850259)
*
* const bytes = new Uint8Array(ulidBuffer)
*
* for (let index = 6; index < 16; index++)
* 	bytes[index] = customRandomByteFunction()
* ```
*/
export declare const makeEmptyUlidBuffer: () => UlidBuffer;
/**
* Set or update the time of a {@linkcode UlidBuffer}.
* @example
* ```js
* // Set to a specific time
* setUlidBufferTime(ulidBuffer, 1469922850259)
*
* // Set to the current time
* setUlidBufferTime(ulidBuffer)
* ```
*/
export declare const setUlidBufferTime: (buffer: UlidBuffer, time?: number) => void;
export declare const setUlidBytesTime: (ulidBytes: UlidBytes, time?: number) => void;
/**
* Retrieve the time from a {@linkcode UlidBuffer}.
* @example
* ```js
* const ulid = toUlid(`01ARZ3NDEKTSV4RRFFQ69G5FAV`)
* const ulidBuffer = decodeUlid(ulid)
* const time = getUlidBufferTime(ulidBuffer)
* const date = new Date(time)
*
* console.log(date.toLocaleString()) // "31/07/2016, 00:54:10"
* ```
*/
export declare const getUlidBufferTime: (buffer: UlidBuffer) => number;
/**
* Make a {@linkcode UlidBuffer}.
*
* This can be useful if you need it as an `ArrayBuffer` first, you can then stringify after.
* @example
* ```js
* const ulidBuffer = makeUlidBuffer()
*
* database.user.create({ id: new Uint8Array(ulidBuffer), … })
*
* console.log(`Created user with id ${makeUlid({ buffer: ulidBuffer })}`)
* ```
*/
export declare const makeUlidBuffer: ({ ulidBuffer, time }?: LaxPartial<{
	/** Reuse a previously used {@linkcode UlidBuffer}. Will be completely overwritten. @default makeEmptyUlidBuffer() */
	ulidBuffer: UlidBuffer;
	/** The time in milliseconds that'll be written into the buffer. @default Date.now() */ time: number;
}>) => UlidBuffer;
export declare const setUlidBytesRandom: (ulidBytes: UlidBytes) => void;
export declare const makeUlidBytes: () => UlidBytes;
export declare const timeToUlidString: (time: number) => string;
export declare const ulidBufferRandomPartToUlidString: (ulidBuffer: UlidBuffer) => Ulid;
export declare const ulidBufferToString: (ulidBuffer: UlidBuffer) => Ulid;
export declare const makeEmptyUlidBytes: () => UlidBytes;
/** Make a [ULID](https://github.com/ulid/spec#readme) string that's narrowed to a {@linkcode Ulid}. */
export declare const makeUlid: () => Ulid;
/** Turn a {@linkcode Ulid} back into an {@linkcode UlidBuffer}. */
export declare const decodeUlid: (ulid: Ulid) => UlidBuffer;
/** Increment the random part of the given {@linkcode UlidBuffer} by 1. */
export declare const incrementUlidBuffer: (ulidBuffer: UlidBuffer, { throwOnOverflow }?: LaxPartial<{
	throwOnOverflow: boolean;
}>) => void;
/** Clone a {@linkcode UlidBuffer}. */
export declare const cloneUlidBuffer: (ulidBuffer: UlidBuffer) => UlidBuffer;
/**
* Make a monotonically incrementing {@linkcode UlidBuffer} generation function. This means if you generate 2
* `UlidBuffer`s using the returned function within the same millisecond, the next one'll simply be an incremented
* version of the previous one.
* @throws If you try to generate another `UlidBuffer` and the previous's random section bytes is all `0xFF`.
* This is mitigated with `mitigateOverflow` which is on by default.
*/
export declare const makeMonotonicallyIncrementingUlidBufferFunction: ({ mitigateOverflow }?: LaxPartial<{
	/**
	* Mitigate the chance of overflow by setting the most significant bit to `0` after generating a new {UlidBuffer}
	* (not when incrementing the previously generated `UlidBuffer`). This should in theory guarantee that you have at
	* least 604 sextillion increments before you hit the overflow which I imagine is incredibly hard, especially in
	* JavaScript.
	*/
	mitigateOverflow: boolean;
}>) => (options?: LaxPartial<{
	ulidBuffer: UlidBuffer;
}>) => UlidBuffer;