export enum ExternalizeErrorCode {
  /** Returned when passed a zero-length string. */
  ZERO_LENGTH_STRING = 1,
  /** Returned when passed a non-two-byte encoded string. */
  INVALID_STRING_ENCODING = 2,
  /** Returned when unable to convert a MaybeLocal to Local. */
  TO_LOCAL_FAILURE = 3,
  /** Returned when IsExternal returns false. */
  EXTERNALIZATION_FAILURE = 4,
}

/**
 * Returns the externalized string when it succeeds or an integer error code
 * otherwise.
 *
 * @example
 * ```js
 * const extern = distringuish.externalize(str);
 * distringuish.getProperties(extern); // => {}
 * ```
 *
 * @example Providing the properties at the time of externalization:
 * ```js
 * const extern = distringuish.externalize(str, { key: 'value' });
 * distringuish.getProperties(extern); // => { key: 'value }
 * ```
 *
 * @example Providing an invalid argument:
 * ```js
 * distringuish.externalize(''); // => 1 === distringuish.ExternalizeErrorCode.ZERO_LENGTH_STRING
 * ```
 */
export function externalize(
  str: string,
  obj?: Record<keyof any, any>,
): string | ExternalizeErrorCode;

/**
 * Returns whether the passed string has previously been externalized.
 * @example
 * ```js
 * const extern = distringuish.externalize(str);
 * distringuish.isExternal(extern) // => true
 * distringuish.isExternal(str) // => false
 * ```
 */
export function isExternal(str: string): boolean;

/**
 * Returns the object associated with a given external string. Returns `null`
 * if the provided argument is not an externalized string or has no associated
 * data.
 *
 * @example
 * ```js
 * const extern = distringuish.externalize(str);
 * const props = distringuish.getProperties(extern); // => {}
 * props.key = 'value';
 * // the object returned maintains properties pinned to the string
 * distringuish.getProperties(extern); // => { key: "value" }
 * ```
 *
 * @example When called with an internal string:
 * ```js
 * const props = distringuish.getProperties(str); // => null
 * ```
 */
export function getProperties(str: string): Record<keyof any, any> | null;

/**
 * Returns a new, non-externalized string and prepares the previous for GC.
 *
 * @example Typical usage:
 * ```js
 * const extern = distringuish.externalize(str);
 * // ... do some work, and once we're done with the externalized string:
 * const intern = distringuish.internalize(extern); // now extern is freed up for garbage collection.
 * ```
 */
export function internalize(str: string): string;