data-custom-id
Version:
Hold data in Discord's Interaction Custom IDs.
189 lines (188 loc) • 8.18 kB
TypeScript
declare type DataCustomIdFieldValue = string | string[];
declare type EncodableDataCustomIdFieldValue = boolean | number | number[] | null | DataCustomIdFieldValue;
export interface DataCustomIdFields {
[key: string]: DataCustomIdFieldValue | EncodableDataCustomIdFieldValue;
}
export interface DataCustomIdEncodeOptions {
/**
* Saves Custom ID space by not encoding [falsy values](https://developer.mozilla.org/en-US/docs/Glossary/Falsy).
* This means values like `0`, `false`, `""`, `[]`, etc. will be omitted from serialization.
*
* Defaults to `true`.
*
* Helps save space, but means that falsy values will not be encoded at all-- if your fields object
* looks like `{ foo: "", bar: 0 }`, after encoding and decoding, your resulting fields
* object will be `{}`, as both `""` and `0` are falsy.
*
* Both `!originalFields.foo` and `!originalFields.bar` are true, and so are `!fields.foo` and `!fields.bar`.
* However, `typeof originalFields.foo === "string"` whereas `typeof fields.foo === "undefined"`.
*
* If you use helper functions like `getStringField`, `getNumberField`, etc., you can use this option safely--
* those helper functions will return an empty value (`""` for string, `0` for number, etc.) if the field doesn't exist.
* However, if you read raw fields, this might matter.
*
* @default true
*/
skipFalsyValues?: boolean;
/**
* Saves space by encoding the value `true` as `1` instead of `"true"`.
*
* Defaults to `false`, because, sometimes, an empty value can mean something other than plain `false`.
*
* If you use the helper function `getBooleanField`, you can use this option safely-- it will return `true`.
* However, if you read raw fields, this might matter.
*
* @default false
*/
convertTrueToOne?: boolean;
}
export declare const defaultEncodeOptions: DataCustomIdEncodeOptions;
/**
* DataCustomIdLengthError is thrown by `DataCustomId.toString()` when the
* length of the resulting string is greater than Discord's maximum length of 100 characters.
*/
export declare class DataCustomIdLengthError extends Error {
constructor(message: string);
}
/**
* DataCustomId lets you store data inside Discord's Custom ID system.
* This is useful for storing state within multi-interaction flows.
*
* Data is stored using a system similar to URL query strings appended to
* the provided custom ID.
*
* It's important to note that you **can not** guarantee data integrity.
* Custom IDs are sent by the client, and can be modified by users.
* **DO NOT INCLUDE SENSITIVE DATA IN CUSTOM IDS!**.
*
* Once instances are created, the raw Custom ID (`customId.rawId`) is immutable.
* If you want to keep the current state and change the raw ID, you can
* create a new instance with the new raw ID, then call `newCustomId.copyFieldsFrom(oldCustomId)`.
*
* @author iamtheyammer
*/
export default class DataCustomId {
/**
* The raw Custom ID string.
*/
readonly rawId: string;
readonly pathParts: string[];
private fields;
/**
* Creates a new DataCustomId instance with a given Custom ID which
* may or may not contain data.
*
* Fields should be strings, optionally separated by `/` characters.
* This will allow you to use `customId.pathParts`.
*
* If a custom ID is provided, it will be parsed,
* allowing you to use methods like `getFields` and `addFields`.
*
* Custom IDs with**out** data must not have `?` or `&` characters.
* Those characters are used to store data.
*
* Discord limits Custom IDs to 100 characters, but this limit is not enforced
* until you call `toString()`.
*
* @param id {string} The raw custom ID with or without fields appended.
*/
constructor(id?: string);
/**
* Adds a field to the custom ID.
*
* Keep names and values short to avoid hitting Discord's limit, which is not enforced
* until you call `toString()`.
*
* @param key The key (name) of the field.
* @param value Its value: a string, array of strings, or boolean.
*/
addField(key: string, value: EncodableDataCustomIdFieldValue): DataCustomId;
/**
* Add multiple fields to the custom ID.
* Overwrites existing fields with the same name.
* @param fields Fields to add to the custom ID.
* @returns The current instance for chaining.
*/
addFields(fields: DataCustomIdFields): DataCustomId;
/**
* Removes a field from the custom ID.
* @param key The key (name) of the field to remove.
* @returns The current instance for chaining.
*/
removeField(key: string): DataCustomId;
/**
* Copies all fields from another custom ID to this custom ID.
* Useful for continuing state from one custom ID to another.
*
* Overwrites existing fields with the same name.
* @param other DataCustomId instance to copy fields from.
* @returns The current instance for chaining.
*/
copyFieldsFrom(other: DataCustomId): DataCustomId;
/**
* Returns all the Custom ID's fields.
*/
getFields(): DataCustomIdFields;
/**
* Returns the value of a field, coalesced to a string.
*
* @param key The key (name) of the field.
* @returns A string with the value, or `""` if the field does not exist.
*/
getStringField(key: string): string;
/**
* Returns the value of a field, coalesced to a string array.
* @param key The key (name) of the field.
* @returns An array of strings, or an empty array if the field does not exist.
*/
getStringArrayField(key: string): string[];
/**
* Returns the value of a field, coalesced to a number or float.
*
* Floats can only have base 10.
*
* @param key The key (name) of the field.
* @param float Whether the number should be parsed with `parseFloat()`. Doesn't support bases. Default false.
* @param base The base to parse the number in. Numbers only (no floats). Default 10.
* @returns A number or `NaN` if the field doesn't exist or isn't a number.
*/
getNumericField(key: string, float?: boolean, base?: number): number;
/**
* Returns the value of a field, coalesced to a number array.
* If the value contains non-numbers, they will be in the return value as NaN.
* Remember to use isNaN() to check for NaN values, not `value === NaN` (that _does not_ work!).
*
* @param key The key (name) of the field.
* @param float Whether the numbers should be parsed with `parseFloat()`. Doesn't support bases. Default false.
* @param base The base to parse the number in. Numbers only (no floats). Default 10.
* @returns A number array, or an empty array if the field does not exist.
*/
getNumericArrayField(key: string, float?: boolean, base?: number): number[];
/**
* Returns the value of a field, coalesced to a boolean.
* If the value of the field is not `true` or `1`, it will be `false`.
*
* @param key The key (name) of the field.
* @returns A boolean with the value, or `false` if the field does not exist.
*/
getBooleanField(key: string): boolean;
/**
* Compresses fields based on the passed-in compression options.
* @param fields The fields to compress.
* @param options Compression options.
* @returns A new object with compressed fields.
* @private
*/
private static compressFields;
/**
* Returns the raw ID string with all fields encoded.
*
* A Custom ID `/ban` with fields `{ "reason": "spam"}` should return `/ban?reason=spam`.
* `true` and falsy values may or may not be encoded depending on selected options.
*
* @throws {DataCustomIdLengthError} if the serialized string is over Discord's 100-character limit.
* @returns The Custom ID value with all fields encoded. Use this as the value for the Custom ID field in a Discord API request.
*/
toString(compressionOptions?: DataCustomIdEncodeOptions): string;
}
export {};