ketting 8.2.0 → 8.4.0

package/dist/browser/index.d.mts

@@ -0,0 +1,1511 @@
+import { LinkHints } from "hal-types";
+import { EventEmitter } from "node:events";
+
+//#region src/http/fetcher.d.ts
+type FetchMiddleware = (request: Request, next: (request: Request) => Promise<Response>) => Promise<Response>;
+/**
+ * The fetcher object is responsible for calling fetch()
+ *
+ * This is wrapped in an object because we want to support
+ * 'fetch middlewares'. These middlewares are similar to server-side
+ * middlewares and can intercept requests and alter requests/responses.
+ */
+declare class Fetcher {
+  middlewares: [RegExp, FetchMiddleware][];
+  advertiseKetting: boolean;
+  /**
+   * A wrapper for MDN fetch()
+   *
+   * This wrapper supports 'fetch middlewares'. It will call them
+   * in sequence.
+   */
+  fetch(resource: string | Request, init?: RequestInit): Promise<Response>;
+  /**
+   * Returns the list of middlewares that are applicable to
+   * a specific origin
+   */
+  getMiddlewaresByOrigin(origin: string): FetchMiddleware[];
+  /**
+   * Add a middleware
+   */
+  use(mw: FetchMiddleware, origin?: string): void;
+  /**
+   * Does a HTTP request and throws an exception if the server emitted
+   * a HTTP error.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/Request/Request
+   */
+  fetchOrThrow(resource: string | Request, init?: RequestInit): Promise<Response>;
+}
+//#endregion
+//#region src/field.d.ts
+type Field = BooleanField | BasicStringField | DateTimeField | FileField | HiddenField | NumberField | SelectFieldSingle | SelectFieldMulti | RangeStringField | TextAreaField | TextField;
+/**
+ * A Field describes a single field in an action or form.
+ *
+ * Fields can be used to automatically render forms or other UIs based on
+ * hypermedia actions.
+ */
+interface BaseField<T> {
+  /**
+   * Name of the field.
+   *
+   * Typically this is the property that will get sent to a server.
+   */
+  name: string;
+  /**
+   * Type describes the type of the property.
+   *
+   * This is similar to the HTML5 "type" attribute on forms.
+   */
+  type: string;
+  /**
+   * This could be used to describe a sample value.
+   */
+  placeholder?: T;
+  /**
+   * Whether this field is required for submitting the form.
+   */
+  required: boolean;
+  /**
+   * Render the field as read-only.
+   */
+  readOnly: boolean;
+  /**
+   * A human-readable label for the field.
+   */
+  label?: string;
+}
+interface SingleValueField<T> extends BaseField<T> {
+  /**
+   * The current (pre-filed) value on the form.
+   */
+  value?: T;
+}
+/**
+ * The base type for things that are range-like.
+ *
+ * This includes numbers, dates and time fields.
+ */
+interface RangeField<T> extends SingleValueField<T> {
+  max?: number;
+  min?: number;
+  step?: number;
+}
+/**
+ * Toggles/checkboxes
+ */
+interface BooleanField extends SingleValueField<boolean> {
+  type: 'checkbox' | 'radio';
+}
+/**
+ * Any field that encodes itself as a string but with no
+ * special features.
+ */
+interface BasicStringField extends SingleValueField<string> {
+  type: 'color' | 'email' | 'password' | 'search' | 'tel' | 'url';
+  minLength?: number;
+  maxLength?: number;
+}
+interface RangeStringField extends RangeField<string> {
+  type: 'date' | 'month' | 'time' | 'week';
+}
+interface DateTimeField extends RangeField<Date> {
+  type: 'datetime' | 'datetime-local';
+}
+interface HiddenField extends SingleValueField<string | number | null | boolean> {
+  type: 'hidden';
+}
+interface FileField extends SingleValueField<never> {
+  type: 'file';
+}
+interface NumberField extends RangeField<number> {
+  type: 'number' | 'range';
+}
+/**
+ * OptionsDataSource is a helper type that specifiess the different data
+ * sources for lists of options.
+ */
+type OptionsDataSource = {
+  /**
+   * Keys and values are labels and values.
+   *
+   * If specified as a plain array, use array values as labels and values.
+   */
+  options: Record<string, string> | string[];
+} | {
+  /**
+   * If dataSource is specified, we'll grab the list of options from a
+   * simple csv or json resource.
+   */
+  dataSource: {
+    /**
+     * URI where the list of options can be acquired.
+     */
+    href: string;
+    /**
+     * Could be text/csv or any json content-type.
+     */
+    type?: string;
+    /**
+     * If datasource returns an array of objects, use this
+     * property for the label. Defaults to 'label'
+     *
+     * This is ignored if it doesn't apply for the media type.
+     */
+    labelField?: string;
+    /**
+     * If datasource returns an array of objects, use this
+     * property for the value. Defaults to 'value'
+     *
+     * This is ignored if it doesn't apply for the media type.
+     */
+    valueField?: string;
+  };
+} | {
+  /**
+   * If 'linkSource' is specified, we assume that the value will be a URI.
+   *
+   * We will grab the list of options by fetching a resource, and getting
+   * a list of links specified by a rel.
+   */
+  linkSource: {
+    href: string;
+    rel: string;
+  };
+};
+/**
+ * Encodes a field that has a list of options a user can choose from.
+ */
+type SelectFieldSingle = BaseField<string> & {
+  type: 'select';
+  renderAs?: 'radio' | 'dropdown';
+  multiple?: false;
+  /**
+   * The current (pre-filed) value on the form.
+   */
+  selectedValue?: string;
+  /**
+   * The current (pre-filed) value on the form.
+   * @deprecated Use selectedValue instead
+   */
+  value?: string;
+} & OptionsDataSource;
+/**
+ * An options field where users can select more than 1 item
+ */
+type SelectFieldMulti = BaseField<string> & {
+  type: 'select';
+  renderAs?: 'checkbox' | 'dropdown';
+  multiple: true;
+  /**
+   * The current (pre-filed) values on the form.
+   */
+  selectedValues?: string[];
+  /**
+   * The current (pre-filed) value on the form.
+   * @deprecated Use selectedValues instead
+   */
+  value?: string;
+} & OptionsDataSource;
+interface TextField extends SingleValueField<string> {
+  type: 'text';
+  minLength?: number;
+  maxLength?: number;
+  pattern?: RegExp;
+}
+interface TextAreaField extends SingleValueField<string> {
+  type: 'textarea';
+  minLength?: number;
+  maxLength?: number;
+  cols?: number;
+  rows?: number;
+}
+//#endregion
+//#region src/action.d.ts
+interface ActionInfo {
+  /**
+   * What url to post the form to.
+   */
+  uri: string;
+  /**
+   * Action name.
+   *
+   * Some formats call this the 'rel'
+   */
+  name: string | null;
+  /**
+   * Form title.
+   *
+   * Should be human-friendly.
+   */
+  title?: string;
+  /**
+   * The HTTP method to use
+   */
+  method: string;
+  /**
+   * The contentType to use for the form submission
+   */
+  contentType: string;
+  /**
+   * Returns the list of fields associated to an action
+   */
+  fields: Field[];
+}
+/**
+ * An action represents a hypermedia form submission or action.
+ */
+interface Action<T extends Record<string, any> = Record<string, any>> extends ActionInfo {
+  /**
+   * Execute the action or submit the form.
+   */
+  submit(formData: T): Promise<State>;
+  /**
+   * Return a field by name.
+   */
+  field(name: string): Field | undefined;
+  /**
+   * Execute the action or submit the form, then return the next resource.
+   *
+   * If a server responds with a 201 Status code and a Location header,
+   * it will automatically return the newly created resource.
+   *
+   * If the server responded with a 204 or 205, this function will return
+   * `this`.
+   */
+  submitFollow(formData: T): Promise<Resource>;
+}
+//#endregion
+//#region src/link.d.ts
+type Link = {
+  /**
+   * Target URI
+   */
+  href: string;
+  /**
+   * Context URI.
+   *
+   * Used to resolve relative URIs
+   */
+  context: string;
+  /**
+   * Relation type
+   */
+  rel: string;
+  /**
+   * Link title
+   */
+  title?: string;
+  /**
+   * Content type hint of the target resource
+   */
+  type?: string;
+  /**
+   * Anchor.
+   *
+   * This describes where the link is linked from, from for example
+   * a fragment in the current document
+   */
+  anchor?: string;
+  /**
+   * Language of the target resource
+   */
+  hreflang?: string;
+  /**
+   * HTML5 media attribute
+   */
+  media?: string;
+  /**
+   * If templated is set to true, the href is a templated URI.
+   */
+  templated?: boolean;
+  /**
+   * Link hints, as defined in draft-nottingham-link-hint
+   */
+  hints?: LinkHints;
+  /**
+   * Link name
+   *
+   * This is sometimes used as a machine-readable secondary key for links.
+   *
+   * This is at least used in HAL, but there may be other formats:
+   *
+   * @see https://datatracker.ietf.org/doc/html/draft-kelly-json-hal-06#section-5.5
+   */
+  name?: string;
+};
+type NewLink = Omit<Link, 'context'>;
+/**
+ * Links container, providing an easy way to manage a set of links.
+ */
+declare class Links {
+  defaultContext: string;
+  private store;
+  constructor(defaultContext: string, links?: Link[] | Links);
+  /**
+   * Adds a link to the list
+   */
+  add(...links: (Link | NewLink)[]): void;
+  add(rel: string, href: string): void;
+  /**
+   * Set a link
+   *
+   * If a link with the provided 'rel' already existed, it will be overwritten.
+   */
+  set(link: Link | NewLink): void;
+  set(rel: string, href: string): void;
+  /**
+   * Return a single link by its 'rel'.
+   *
+   * If the link does not exist, undefined is returned.
+   */
+  get(rel: string): Link | undefined;
+  /**
+    * Delete all links with the given 'rel'.
+   *
+   * If the second argument is provided, only links that match the href will
+   * be removed.
+   */
+  delete(rel: string, href?: string): void;
+  /**
+   * Return all links that have a given rel.
+   *
+   * If no links with the rel were found, an empty array is returned.
+   */
+  getMany(rel: string): Link[];
+  /**
+   * Return all links.
+   */
+  getAll(): Link[];
+  /**
+   * Returns true if at least 1 link with the given rel exists.
+   */
+  has(rel: string): boolean;
+}
+/**
+ * The LinkNotFound error gets thrown whenever something tries to follow a
+ * link by its rel, that doesn't exist
+ */
+declare class LinkNotFound extends Error {}
+/**
+ * A key->value map of variables to place in a templated link
+ */
+type LinkVariables = {
+  [key: string]: string | number | string[] | number[];
+};
+//#endregion
+//#region src/state/interface.d.ts
+type State<T = any> = {
+  /**
+   * The URI associated with this state
+   */
+  uri: string;
+  /**
+   * Represents the body of the HTTP response.
+   *
+   * In the case of a JSON response, this will be deserialized
+   */
+  data: T;
+  /**
+   * All links associated with the resource.
+   */
+  links: Links;
+  /**
+   * The full list of HTTP headers that were sent with the response.
+   */
+  headers: Headers;
+  /**
+   * Reference to main client that created this state
+   */
+  client: Client;
+  /**
+   * Follows a relationship, based on its reltype. For example, this might be
+   * 'alternate', 'item', 'edit' or a custom url-based one.
+   *
+   * This function can also follow templated uris. You can specify uri
+   * variables in the optional variables argument.
+   */
+  follow<TFollowedResource = any>(rel: string, variables?: LinkVariables): Resource<TFollowedResource>;
+  /**
+   * Follows a relationship based on its reltype. This function returns a
+   * Promise that resolves to an array of Resource objects.
+   *
+   * If no resources were found, the array will be empty.
+   */
+  followAll<TFollowedResource = any>(rel: string): Resource<TFollowedResource>[];
+  /**
+   * Return an action by name.
+   *
+   * If the format provides a default action, the name may be omitted.
+   */
+  action<TFormData extends Record<string, any> = any>(name?: string): Action<TFormData>;
+  /**
+   * Find an action by name.
+   *
+   * If the format provides a default action, the name may be omitted.
+   */
+  findAction<TFormData extends Record<string, any> = any>(name?: string): Action<TFormData> | undefined;
+  /**
+   * Returns all actions
+   */
+  actions(): Action[];
+  /**
+   * Checks if the specified action exists.
+   *
+   * If no name is given, checks if _any_ action exists.
+   */
+  hasAction(name?: string): boolean;
+  /**
+   * Returns a serialization of the state that can be used in a HTTP
+   * response.
+   *
+   * For example, a JSON object might simply serialize using
+   * JSON.serialize().
+   */
+  serializeBody(): Buffer | Blob | string;
+  /**
+   * Content-headers are a subset of HTTP headers that related directly
+   * to the content. The obvious ones are Content-Type.
+   *
+   * This set of headers will be sent by the server along with a GET
+   * response, but will also be sent back to the server in a PUT
+   * request.
+   */
+  contentHeaders(): Headers;
+  /**
+   * Some formats support embedding resources inside other resources.
+   *
+   * Please note: generally you should always use the .follow() and
+   * .followAll() functions to get access to linked embedded resources.
+   *
+   * There's several operations that change the State in the Ketting Cache,
+   * and usually this erases any associated embedded resources.
+   *
+   * .follow() and .followAll() will return the embedded resources, and also
+   * keeps their respective states fresh when changes are made.
+   */
+  getEmbedded(): State[];
+  /**
+   * Timestamp of when the State was first generated
+   */
+  timestamp: number;
+  clone(): State<T>;
+};
+/**
+ * HeadState represents the response to a HEAD request.
+ *
+ * Some information in HEAD responses might be available, but many aren't.
+ * Notably, the body.
+ */
+type HeadState = Omit<State, 'data' | 'action' | 'findAction' | 'actions' | 'hasAction' | 'serializeBody' | 'getEmbedded' | 'client' | 'clone'>;
+/**
+ * A 'StateFactory' is responsible for taking a Fetch Response, and returning
+ * an object that impements the State interface
+ */
+type StateFactory<T = any> = (client: Client, uri: string, request: Response) => Promise<State<T>>;
+declare function isState(input: Record<string, any>): input is State;
+//#endregion
+//#region src/state/base-state.d.ts
+type HeadStateInit = {
+  client: Client;
+  uri: string;
+  links: Links;
+  /**
+   * The full list of HTTP headers that were sent with the response.
+   */
+  headers: Headers;
+};
+type StateInit<T> = {
+  client: Client;
+  uri: string;
+  data: T;
+  headers: Headers;
+  links: Links;
+  embedded?: State[];
+  actions?: ActionInfo[];
+};
+/**
+ * Implements a State object for HEAD responses
+ */
+declare class BaseHeadState implements HeadState {
+  uri: string;
+  /**
+   * Timestamp of when the State was first generated
+   */
+  timestamp: number;
+  /**
+   * The full list of HTTP headers that were sent with the response.
+   */
+  headers: Headers;
+  /**
+   * All links associated with the resource.
+   */
+  links: Links;
+  /**
+   * Reference to main client that created this state
+   */
+  client: Client;
+  constructor(init: HeadStateInit);
+  /**
+   * Follows a relationship, based on its reltype. For example, this might be
+   * 'alternate', 'item', 'edit' or a custom url-based one.
+   *
+   * This function can also follow templated uris. You can specify uri
+   * variables in the optional variables argument.
+   */
+  follow<TFollowedResource = any>(rel: string, variables?: LinkVariables): Resource<TFollowedResource>;
+  /**
+   * Follows a relationship based on its reltype. This function returns a
+   * Promise that resolves to an array of Resource objects.
+   *
+   * If no resources were found, the array will be empty.
+   */
+  followAll<TFollowedResource = any>(rel: string): Resource<TFollowedResource>[];
+  /**
+   * Content-headers are a subset of HTTP headers that related directly
+   * to the content. The obvious ones are Content-Type.
+   *
+   * This set of headers will be sent by the server along with a GET
+   * response, but will also be sent back to the server in a PUT
+   * request.
+   */
+  contentHeaders(): Headers;
+}
+/**
+ * The Base State provides a convenient way to implement a new State type.
+ */
+declare class BaseState<T> extends BaseHeadState implements State<T> {
+  data: T;
+  protected embedded: State[];
+  protected actionInfo: ActionInfo[];
+  constructor(init: StateInit<T>);
+  /**
+   * Return an action by name.
+   *
+   * If no name is given, the first action is returned. This is useful for
+   * formats that only supply 1 action, and no name.
+   */
+  action<TFormData extends Record<string, any> = any>(name?: string): Action<TFormData>;
+  findAction<TFormData extends Record<string, any> = any>(name?: string): Action<TFormData> | undefined;
+  private doFindAction;
+  /**
+   * Returns all actions
+   */
+  actions(): Action[];
+  /**
+   * Checks if the specified action exists.
+   *
+   * If no name is given, checks if _any_ action exists.
+   */
+  hasAction(name?: string): boolean;
+  /**
+   * Returns a serialization of the state that can be used in a HTTP
+   * response.
+   *
+   * For example, a JSON object might simply serialize using
+   * JSON.serialize().
+   */
+  serializeBody(): Buffer | Blob | string;
+  /**
+   * Certain formats can embed other resources, identified by their
+   * own URI.
+   *
+   * When a format has embedded resources, we will use these to warm
+   * the cache.
+   *
+   * This method returns every embedded resource.
+   */
+  getEmbedded(): State[];
+  clone(): State<T>;
+}
+//#endregion
+//#region src/state/hal.d.ts
+/**
+ * Represents a resource state in the HAL format
+ */
+declare class HalState<T = any> extends BaseState<T> {
+  serializeBody(): string;
+  private serializeLinks;
+  clone(): HalState<T>;
+}
+//#endregion
+//#region src/state/siren.d.ts
+/**
+ * Represents a resource state in the Siren format
+ */
+declare class SirenState<T> extends BaseState<T> {
+  /**
+   * Returns a serialization of the state that can be used in a HTTP
+   * response.
+   *
+   * For example, a JSON object might simply serialize using
+   * JSON.serialize().
+   */
+  serializeBody(): string;
+  clone(): SirenState<T>;
+}
+//#endregion
+//#region src/state/collection-json.d.ts
+/**
+ * Represents a resource state in the HAL format
+ */
+declare class CjState<T = any> extends BaseState<T> {
+  serializeBody(): string;
+}
+//#endregion
+//#region src/types.d.ts
+type HttpHeaders = Record<string, string>;
+/**
+ * RequestOptions is a set of properties that define
+ * a request, or state change.
+ *
+ * Everything is usually optional.
+ */
+type RequestOptions<T = any> = {
+  /**
+   * Should return a string or a Buffer.
+   *
+   * Will be used as the body in the HTTP request.
+   * If not set, `body` will be used instead.
+   */
+  serializeBody?: () => string | Buffer | Blob;
+  /**
+   * If set, contains the body of the current state.
+   *
+   * If body is not a `string` or a `Buffer`, the body will
+   * be json encoded.
+   */
+  data?: T;
+  /**
+   * List of headers that will be set in the request.
+   *
+   * If this is not set, we'll fall back to 'headers'
+   */
+  getContentHeaders?: () => HttpHeaders | Headers;
+  /**
+   * Full list of HTTP headers.
+   */
+  headers?: HttpHeaders | Headers;
+};
+type GetRequestOptions = Omit<RequestOptions, 'serializeBody' | 'data'>;
+type HeadRequestOptions = GetRequestOptions;
+type PatchRequestOptions<T = any> = RequestOptions<T>;
+type PutRequestOptions<T = any> = RequestOptions<T>;
+type PostRequestOptions<T = any> = RequestOptions<T>;
+//#endregion
+//#region src/follow-promise.d.ts
+/**
+ * Base interface for both FollowOne and FollowAll
+ */
+declare abstract class FollowPromise<T> implements PromiseLike<T> {
+  protected prefetchEnabled: boolean;
+  protected preferTranscludeEnabled: boolean;
+  protected useHeadEnabled: boolean;
+  constructor();
+  preFetch(): this;
+  preferTransclude(): this;
+  /**
+   * Use a HTTP HEAD request to fetch the links.
+   *
+   * This is useful when interacting with servers that embed links in Link
+   * Headers.
+   */
+  useHead(): this;
+  abstract then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null): PromiseLike<TResult1 | TResult2>;
+  abstract catch<TResult1 = T, TResult2 = never>(onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null): PromiseLike<TResult1 | TResult2>;
+}
+/**
+ * The FollowPromise class is what's being returned from follow() functions.
+ *
+ * It's 'PromiseLike', which means you can treat it like a Promise, and it
+ * can be awaited. When used as a Promise, it resolves to the Resource object
+ * that was followed.
+ *
+ * In addition to being a Promise<Resource> stand-in, it also exposes other
+ * functions, namely:
+ *
+ * * `follow()` to allow a user to chain several follow() functions to do
+ *   several 'hops' all at once.
+ * * `followAll()`, allowing a user to call `followAll()` at the end of a
+ *   chain.
+ */
+declare class FollowPromiseOne<T = any> extends FollowPromise<Resource<T>> {
+  private resource;
+  private rel;
+  private variables?;
+  constructor(resource: Resource | Promise<Resource>, rel: string, variables?: LinkVariables);
+  /**
+   * This 'then' function behaves like a Promise then() function.
+   *
+   * This method signature is pretty crazy, but trust that it's pretty much
+   * like any then() method on a promise.
+   */
+  then<TResult1 = Resource<T>, TResult2 = never>(onfulfilled?: ((value: Resource<T>) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: Error) => TResult2 | PromiseLike<TResult2>) | null | undefined): Promise<TResult1 | TResult2>;
+  /**
+   * This 'catch' function behaves like a Promise catch() function.
+   */
+  catch<TResult1 = any, TResult2 = never>(onrejected?: ((reason: Error) => TResult2 | PromiseLike<TResult2>) | null | undefined): Promise<TResult1 | TResult2>;
+  /**
+   * Implementation of a Promise.finally function
+   */
+  finally<TResult1 = any>(onfinally: () => TResult1 | PromiseLike<TResult1>): Promise<TResult1>;
+  /**
+   * Follow another link immediately after following this link.
+   *
+   * This allows you to follow several hops of links in one go.
+   *
+   * For example: resource.follow('foo').follow('bar');
+   */
+  follow<TNested = any>(rel: string, variables?: LinkVariables): FollowPromiseOne<TNested>;
+  /**
+   * Gets the current state of the resource.
+   *
+   * This function will return a State object.
+   */
+  get(getOptions?: GetRequestOptions): Promise<State<T>>;
+  /**
+   * Follows a set of links immediately after following this link.
+   *
+   * For example: resource.follow('foo').followAll('item');
+   */
+  followAll<TNested = any>(rel: string): FollowPromiseMany<TNested>;
+  /**
+   * This function does the actual fetching of the linked
+   * resource.
+   */
+  private fetchLinkedResource;
+}
+/**
+ */
+declare class FollowPromiseMany<T = any> extends FollowPromise<Resource<T>[]> {
+  private resource;
+  private rel;
+  constructor(resource: Resource | Promise<Resource>, rel: string);
+  /**
+   * This 'then' function behaves like a Promise then() function.
+   */
+  then<TResult1 = Resource<T>[], TResult2 = never>(onfulfilled?: ((value: Resource<T>[]) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: Error) => TResult2 | PromiseLike<TResult2>) | null | undefined): Promise<TResult1 | TResult2>;
+  /**
+   * This 'catch' function behaves like a Promise catch() function.
+   */
+  catch<TResult1 = any, TResult2 = never>(onrejected?: ((reason: Error) => TResult2 | PromiseLike<TResult2>) | null | undefined): Promise<TResult1 | TResult2>;
+  /**
+   * Implementation of a Promise.finally function
+   */
+  finally<TResult1 = any>(onfinally: () => TResult1 | PromiseLike<TResult1>): Promise<TResult1>;
+  /**
+   * Gets the current states of the resources.
+   *
+   * This function will return an array of State object.
+   */
+  get(getOptions?: GetRequestOptions): Promise<State<T>[]>;
+  /**
+   * This function does the actual fetching, to obtained the url
+   * of the linked resource. It returns the Resource object.
+   */
+  private fetchLinkedResources;
+}
+//#endregion
+//#region src/resource.d.ts
+/**
+ * A 'resource' represents an endpoint on a server.
+ *
+ * A resource has a uri, methods that correspond to HTTP methods,
+ * and events to subscribe to state changes.
+ */
+declare class Resource<T = any> extends EventEmitter {
+  /**
+   * URI of the current resource
+   */
+  uri: string;
+  /**
+   * Reference to the Client that created the resource
+   */
+  client: Client;
+  /**
+   * This object tracks all in-flight requests.
+   *
+   * When 2 identical requests are made in quick succession, this object is
+   * used to de-duplicate the requests.
+   */
+  private readonly activeRefresh;
+  /**
+   * Create the resource.
+   *
+   * This is usually done by the Client.
+   */
+  constructor(client: Client, uri: string);
+  /**
+   * Gets the current state of the resource.
+   *
+   * This function will return a State object.
+   */
+  get(getOptions?: GetRequestOptions): Promise<State<T>>;
+  /**
+   * Does a HEAD request and returns a HeadState object.
+   *
+   * If there was a valid existing cache for a GET request, it will
+   * still return that.
+   */
+  head(headOptions?: HeadRequestOptions): Promise<HeadState>;
+  /**
+   * Gets the current state of the resource, skipping
+   * the cache.
+   *
+   * This function will return a State object.
+   */
+  refresh(getOptions?: GetRequestOptions): Promise<State<T>>;
+  /**
+   * Updates the server state with a PUT request
+   */
+  put(options: PutRequestOptions<T> | State): Promise<void>;
+  /**
+   * Deletes the resource
+   */
+  delete(): Promise<void>;
+  /**
+   * Sends a POST request to the resource.
+   *
+   * See the documentation for PostRequestOptions for more details.
+   * This function is used for RPC-like endpoints and form submissions.
+   *
+   * This function will return the response as a State object.
+   */
+  post(options: PostRequestOptions): Promise<State>;
+  /**
+   * Sends a POST request, and follows to the next resource.
+   *
+   * If a server responds with a 201 Status code and a Location header,
+   * it will automatically return the newly created resource.
+   *
+   * If the server responded with a 204 or 205, this function will return
+   * `this`.
+   */
+  postFollow(options: PostRequestOptions): Promise<Resource>;
+  /**
+   * Sends a PATCH request to the resource.
+   *
+   * This function defaults to a application/json content-type header.
+   *
+   * If the server responds with 200 Status code this will return a State object
+   */
+  patch(options: PatchRequestOptions): Promise<undefined | State<T>>;
+  /**
+   * Follows a relationship, based on its reltype. For example, this might be
+   * 'alternate', 'item', 'edit' or a custom url-based one.
+   *
+   * This function can also follow templated uris. You can specify uri
+   * variables in the optional variables argument.
+   */
+  follow<TFollowedResource = any>(rel: string, variables?: LinkVariables): FollowPromiseOne<TFollowedResource>;
+  /**
+   * Follows a relationship based on its reltype. This function returns a
+   * Promise that resolves to an array of Resource objects.
+   *
+   * If no resources were found, the array will be empty.
+   */
+  followAll<TFollowedResource = any>(rel: string): FollowPromiseMany<TFollowedResource>;
+  /**
+   * Resolves a new resource based on a relative uri.
+   *
+   * Use this function to manually get a Resource object via a uri. The uri
+   * will be resolved based on the uri of the current resource.
+   *
+   * This function doesn't do any HTTP requests.
+   */
+  go<TGoResource = any>(uri: string | Link): Resource<TGoResource>;
+  /**
+   * Does a HTTP request on the current resource URI
+   */
+  fetch(init?: RequestInit): Promise<Response>;
+  /**
+   * Does a HTTP request on the current resource URI.
+   *
+   * If the response was a 4XX or 5XX, this function will throw
+   * an exception.
+   */
+  fetchOrThrow(init?: RequestInit): Promise<Response>;
+  /**
+   * Updates the state cache, and emits events.
+   *
+   * This will update the local state but *not* update the server
+   */
+  updateCache(state: State<T>): void;
+  /**
+   * Clears the state cache for this resource.
+   */
+  clearCache(): void;
+  /**
+   * Retrieves the current cached resource state, and return `null` if it's
+   * not available.
+   */
+  getCache(): State<T> | null;
+  /**
+   * Returns a Link object, by its REL.
+   *
+   * If the link does not exist, a LinkNotFound error will be thrown.
+   *
+   * @deprecated
+   */
+  link(rel: string): Promise<Link>;
+  /**
+   * Returns all links defined on this object.
+   *
+   * @deprecated
+   */
+  links(rel?: string): Promise<Link[]>;
+  /**
+   *
+   * Returns true or false depending on if a link with the specified relation
+   * type exists.
+   *
+   * @deprecated
+   */
+  hasLink(rel: string): Promise<boolean>;
+}
+declare interface Resource<T = any> {
+  /**
+   * Subscribe to the 'update' event.
+   *
+   * This event will get triggered whenever a new State is received
+   * from the server, either through a GET request or if it was
+   * transcluded.
+   *
+   * It will also trigger when calling 'PUT' with a full state object,
+   * and when updateCache() was used.
+   */
+  on(event: 'update', listener: (state: State) => void): this;
+  /**
+   * Subscribe to the 'stale' event.
+   *
+   * This event will get triggered whenever an unsafe method was
+   * used, such as POST, PUT, PATCH, etc.
+   *
+   * When any of these methods are used, the local cache is stale.
+   */
+  on(event: 'stale', listener: () => void): this;
+  /**
+   * Subscribe to the 'delete' event.
+   *
+   * This event gets triggered when the `DELETE` http method is used.
+   */
+  on(event: 'delete', listener: () => void): this;
+  /**
+   * Subscribe to the 'update' event and unsubscribe after it was
+   * emitted the first time.
+   */
+  once(event: 'update', listener: (state: State) => void): this;
+  /**
+   * Subscribe to the 'stale' event and unsubscribe after it was
+   * emitted the first time.
+   */
+  once(event: 'stale', listener: () => void): this;
+  /**
+   * Subscribe to the 'delete' event and unsubscribe after it was
+   * emitted the first time.
+   */
+  once(event: 'delete', listener: () => void): this;
+  /**
+   * Unsubscribe from the 'update' event
+   */
+  off(event: 'update', listener: (state: State) => void): this;
+  /**
+   * Unsubscribe from the 'stale' event
+   */
+  off(event: 'stale', listener: () => void): this;
+  /**
+   * Unsubscribe from the 'delete' event
+   */
+  off(event: 'delete', listener: () => void): this;
+  /**
+   * Emit an 'update' event.
+   */
+  emit(event: 'update', state: State): boolean;
+  /**
+   * Emit a 'stale' event.
+   */
+  emit(event: 'stale'): boolean;
+  /**
+   * Emit a 'delete' event.
+   */
+  emit(event: 'delete'): boolean;
+}
+//#endregion
+//#region src/cache/forever.d.ts
+/**
+ * The 'Forever' cache stores any State for as long as the application
+ * lives.
+ *
+ * It is a good default for most applications, but it means that if
+ * a resource was changed server-side, Ketting will not pick up that change
+ * until something was done to expire caches.
+ *
+ * Executing an unsafe method, calling clearCache() on a resource, or
+ * when a resource appears in Location, Content-Location, or "invalidates"
+ * link relationships.
+ */
+declare class ForeverCache implements StateCache {
+  private cache;
+  constructor();
+  /**
+   * Store a State object.
+   *
+   * This function will clone the state object before storing
+   */
+  store(state: State): void;
+  /**
+   * Retrieve a State object from the cache by its absolute uri
+   */
+  get(uri: string): State | null;
+  /**
+   * Return true if a State object with the specified uri exists in the cache
+   */
+  has(uri: string): boolean;
+  /**
+   * Delete a State object from the cache, by its uri
+   */
+  delete(uri: string): void;
+  /**
+   * Purge the entire cache
+   */
+  clear(): void;
+  /**
+   * Clean up any dangling references to avoid memory leaks.
+   */
+  destroy(): void;
+}
+//#endregion
+//#region src/cache/short.d.ts
+/**
+ * ShortCache stores items in the cache for a short time.
+ *
+ * This cache can be a good choice if your server heavily relies
+ * on HTTP cache headers and Ketting runs in your browser, or if in general
+ * you want very up-to-date data.
+ *
+ * The reason in this scenarios it's useful to still have a 'very temporary'
+ * cache, is because during many operations `get()` may be called in rapid
+ * succession, and it also allows for enough time for 'embedded items' to
+ * pe placed in the cache and extracted again.
+ */
+declare class ShortCache extends ForeverCache {
+  private cacheTimeout;
+  private activeTimers;
+  /**
+   * Create the short cache.
+   *
+   * cacheTimeout is specified in ms.
+   */
+  constructor(cacheTimeout?: number);
+  /**
+   * Store a State object.
+   *
+   * This function will clone the state object before storing
+   */
+  store(state: State): void;
+  private setTimer;
+  /**
+   * Clean up any dangling references to avoid memory leaks.
+   */
+  destroy(): void;
+}
+//#endregion
+//#region src/cache/never.d.ts
+/**
+ * The NeverCache caches absolutely nothing.
+ *
+ * This should usually only be used in testing scenarios or if you really
+ * know what you're doing.
+ *
+ * Using it could cause excessive requests, and will cause embedded items
+ * to be ignored.
+ */
+declare class NeverCache implements StateCache {
+  /**
+   * Store a State object.
+   *
+   * This function will clone the state object before storing
+   */
+  store(state: State): void;
+  /**
+   * Retrieve a State object from the cache by its absolute uri
+   */
+  get(uri: string): null;
+  /**
+   * Return true if a State object with the specified uri exists in the cache
+   */
+  has(uri: string): boolean;
+  /**
+   * Delete a State object from the cache, by its uri
+   */
+  delete(uri: string): void;
+  /**
+   * Purge the entire cache
+   */
+  clear(): void;
+}
+//#endregion
+//#region src/cache/index.d.ts
+/**
+ * Cache interface
+ *
+ * The cache is responsible for storing 'state' objects
+ */
+interface StateCache {
+  /**
+   * Store a State object.
+   *
+   * This function will clone the state object before storing
+   */
+  store: (state: State) => void;
+  /**
+   * Retrieve a State object from the cache by its absolute uri
+   */
+  get: (uri: string) => State | null;
+  /**
+   * Return true if a State object with the specified uri exists in the cache
+   */
+  has: (uri: string) => boolean;
+  /**
+   * Delete a State object from the cache, by its uri
+   */
+  delete: (uri: string) => void;
+  /**
+   * Purge the entire cache
+   */
+  clear: () => void;
+}
+//#endregion
+//#region src/client.d.ts
+declare class Client {
+  /**
+   * All relative urls will by default use the bookmarkUri to
+   * expand. It should usually be the starting point of your
+   * API
+   */
+  bookmarkUri: string;
+  /**
+   * Supported content types
+   *
+   * Each content-type has a 'factory' that turns a HTTP response
+   * into a State object.
+   *
+   * The last value in the array is the 'q=' value, used in Accept
+   * headers. Higher means higher priority.
+   */
+  contentTypeMap: {
+    [mimeType: string]: [StateFactory<any>, string];
+  };
+  /**
+   * The cache for 'State' objects
+   */
+  cache: StateCache;
+  /**
+   * The cache for 'Resource' objects. Each unique uri should
+   * only ever get 1 associated resource.
+   */
+  resources: Map<string, Resource>;
+  /**
+   * Fetcher is a utility object that handles fetch() requests
+   * and middlewares.
+   */
+  fetcher: Fetcher;
+  constructor(bookmarkUri: string);
+  /**
+   * Follows a relationship, based on its reltype. For example, this might be
+   * 'alternate', 'item', 'edit' or a custom url-based one.
+   *
+   * This function can also follow templated uris. You can specify uri
+   * variables in the optional variables argument.
+   */
+  follow<TFollowedResource = any>(rel: string, variables?: LinkVariables): FollowPromiseOne<TFollowedResource>;
+  /**
+   * Returns a resource by its uri.
+   *
+   * This function doesn't do any HTTP requests. The uri is optional. If it's
+   * not specified, it will return the bookmark resource.
+   *
+   * If a relative uri is passed, it will be resolved based on the bookmark
+   * uri.
+   *
+   * @example
+   * const res = ketting.go('https://example.org/);
+   * @example
+   * const res = ketting.go<Author>('/users/1');
+   * @example
+   * const res = ketting.go(); // bookmark
+   */
+  go<TResource = any>(uri?: string | Link): Resource<TResource>;
+  /**
+   * Adds a fetch middleware, which will be executed for
+   * each fetch() call.
+   *
+   * If 'origin' is specified, fetch middlewares can be executed
+   * only if the host/origin matches.
+   */
+  use(middleware: FetchMiddleware, origin?: string): void;
+  /**
+   * Clears the entire state cache
+   */
+  clearCache(): void;
+  /**
+   * Caches a State object
+   *
+   * This function will also emit 'update' events to resources, and store all
+   * embedded states.
+   */
+  cacheState(state: State): void;
+  /**
+   * cacheDependencies contains all cache relationships between
+   * resources.
+   *
+   * This lets a user (for example) let a resource automatically
+   * expire, if another one expires.
+   *
+   * A server can populate this list using the `inv-by' link.
+   *
+   * @deprecated This property will go private in a future release.
+   */
+  cacheDependencies: Map<string, Set<string>>;
+  /**
+   * Adds a cache dependency between two resources.
+   *
+   * If the 'target' resource ever expires, it will cause 'dependentUri' to
+   * also expire.
+   *
+   * Both argument MUST be absolute urls.
+   */
+  addCacheDependency(targetUri: string, dependentUri: string): void;
+  /**
+   * Helper function for clearing the cache for a resource.
+   *
+   * This function will also emit the 'stale' event for resources that have
+   * subscribers, and handle any dependent resource caches.
+   *
+   * If any resources are specified in deletedUris, those will not
+   * receive 'stale' events, but 'delete' events instead.
+   */
+  clearResourceCache(staleUris: string[], deletedUris: string[]): void;
+  /**
+   * Transforms a fetch Response to a State object.
+   */
+  getStateForResponse(uri: string, response: Response): Promise<State>;
+}
+//#endregion
+//#region src/util/uri.d.ts
+/**
+ * Resolves a relative url using another url.
+ *
+ * This is the node.js version.
+ */
+declare function resolve(base: string, relative: string): string;
+declare function resolve(link: Link): string;
+//#endregion
+//#region src/util/uri-template.d.ts
+declare function expand(context: string, template: string, vars: LinkVariables): string;
+declare function expand(link: Link, vars: LinkVariables): string;
+//#endregion
+//#region src/http/basic-auth.d.ts
+declare const _default: (userName: string, password: string) => FetchMiddleware;
+//#endregion
+//#region src/http/bearer-auth.d.ts
+declare const _default$1: (token: string) => FetchMiddleware;
+//#endregion
+//#region src/http/oauth2.d.ts
+declare function oauth2mw(oauth2Options: OAuth2Options, token?: OAuth2Token): FetchMiddleware;
+/**
+ * Token information
+ */
+type OAuth2Token = {
+  /**
+   * OAuth2 Access Token
+   */
+  accessToken: string;
+  /**
+   * When the Access Token expires.
+   *
+   * This is expressed as a unix timestamp in milliseconds.
+   */
+  expiresAt: number | null;
+  /**
+   * OAuth2 refresh token
+   */
+  refreshToken: string | null;
+};
+/**
+ * grant_type=password
+ */
+type PasswordGrantOptions = {
+  grantType: 'password';
+  /**
+   * OAuth2 client id
+   */
+  clientId: string;
+  /**
+   * OAuth2 Client Secret
+   */
+  clientSecret: string;
+  /**
+   * OAuth2 token endpoint
+   */
+  tokenEndpoint: string;
+  /**
+   * List of OAuth2 scopes
+   */
+  scope?: string[];
+  /**
+   * Username to log in as
+   */
+  userName: string;
+  /**
+   * Password
+   */
+  password: string;
+  /**
+   * Callback to trigger when a new access/refresh token pair was obtained.
+   */
+  onTokenUpdate?: (token: OAuth2Token) => void;
+  /**
+   * If authentication fails without a chance of recovery, this gets triggered.
+   *
+   * This is used for example when your resource server returns a 401, but only after
+   * other attempts have been made to reauthenticate (such as a token refresh).
+   */
+  onAuthError?: (error: Error) => void;
+};
+/**
+ * grant_type=client_credentials
+ */
+type ClientCredentialsGrantOptions = {
+  grantType: 'client_credentials';
+  /**
+   * OAuth2 client id
+   */
+  clientId: string;
+  /**
+   * OAuth2 Client Secret
+   */
+  clientSecret: string;
+  /**
+   * OAuth2 token endpoint
+   */
+  tokenEndpoint: string;
+  /**
+   * List of OAuth2 scopes
+   */
+  scope?: string[];
+  /**
+   * Callback to trigger when a new access/refresh token pair was obtained.
+   */
+  onTokenUpdate?: (token: OAuth2Token) => void;
+  /**
+   * If authentication fails without a chance of recovery, this gets triggered.
+   *
+   * This is used for example when your resource server returns a 401, but only after
+   * other attempts have been made to reauthenticate (such as a token refresh).
+   */
+  onAuthError?: (error: Error) => void;
+};
+/**
+ * grant_type=authorization_code
+ */
+type AuthorizationCodeGrantOptions = {
+  grantType: 'authorization_code';
+  /**
+   * OAuth2 client id
+   */
+  clientId: string;
+  /**
+   * OAuth2 token endpoint
+   */
+  tokenEndpoint: string;
+  /**
+   * The redirect_uri that was passed originally to the 'authorization' endpoint.
+   *
+   * This must be identical to the original string, as conforming OAuth2 servers
+   * will validate this.
+   */
+  redirectUri: string;
+  /**
+   * Code that was obtained from the authorization endpoint
+   */
+  code: string;
+  /**
+   * Callback to trigger when a new access/refresh token pair was obtained.
+   */
+  onTokenUpdate?: (token: OAuth2Token) => void;
+  /**
+   * If authentication fails without a chance of recovery, this gets triggered.
+   *
+   * This is used for example when your resource server returns a 401, but only after
+   * other attempts have been made to reauthenticate (such as a token refresh).
+   */
+  onAuthError?: (error: Error) => void;
+  /**
+   * When using PKCE, specify the previously generated code verifier here.
+   */
+  codeVerifier?: string;
+};
+/**
+ * In case you obtained an access token and/or refresh token through different
+ * means, you can not specify a grant_type and simply only specify an access
+ * and refresh token.
+ *
+ * If a refresh or tokenEndpoint are not supplied, the token will never get refreshed.
+ */
+type RefreshOnlyGrantOptions = {
+  grantType: undefined;
+  /**
+   * OAuth2 client id
+   */
+  clientId: string;
+  tokenEndpoint: string;
+  /**
+   * Callback to trigger when a new access/refresh token pair was obtained.
+   */
+  onTokenUpdate?: (token: OAuth2Token) => void;
+  /**
+   * If authentication fails without a chance of recovery, this gets triggered.
+   *
+   * This is used for example when your resource server returns a 401, but only after
+   * other attempts have been made to reauthenticate (such as a token refresh).
+   */
+  onAuthError?: (error: Error) => void;
+};
+type OAuth2Options = PasswordGrantOptions | ClientCredentialsGrantOptions | AuthorizationCodeGrantOptions | RefreshOnlyGrantOptions;
+//#endregion
+//#region src/http/error.d.ts
+/**
+ * HttpError extends the Error object, and is thrown wheenever servers emit
+ * HTTP errors.
+ *
+ * It has a response property, allowing users to find out more about the
+ * nature of the error.
+ */
+declare class HttpError extends Error {
+  response: Response;
+  status: number;
+  constructor(response: Response);
+}
+/**
+ * Problem extends the HttpError object. If a server emits a HTTP error, and
+ * the response body's content-type is application/problem+json.
+ *
+ * application/problem+json is defined in RFC7807 and provides a standardized
+ * way to describe error conditions by a HTTP server.
+ */
+declare class Problem extends HttpError {
+  body: {
+    type: string;
+    title?: string;
+    status: number;
+    detail?: string;
+    instance?: string;
+    [x: string]: any;
+  };
+  constructor(response: Response, problemBody: Record<string, any>);
+}
+//#endregion
+export { type Action, BaseHeadState, BaseState, type BasicStringField, type BooleanField, CjState, Client, Client as Ketting, Client as default, type DateTimeField, type FetchMiddleware, type Field, type FileField, FollowPromiseMany, FollowPromiseOne, ForeverCache, HalState, type HiddenField, type Link, LinkNotFound, type LinkVariables, Links, NeverCache, type NumberField, Problem, type RangeStringField, Resource, type SelectFieldMulti, type SelectFieldSingle, ShortCache, SirenState, type State, type StateCache, type TextAreaField, type TextField, _default as basicAuth, _default$1 as bearerAuth, expand, isState, oauth2mw as oauth2, resolve };
+//# sourceMappingURL=index.d.mts.map