@php-skir/skir-client 1.0.19

package/dist/esm/skir-client.d.ts

@@ -0,0 +1,1051 @@
+import type { Express as ExpressApp, json as ExpressJson, raw as ExpressRaw, Request as ExpressRequest, text as ExpressText } from "express";
+/**
+ * A single moment in time represented in a platform-independent format, with a
+ * precision of one millisecond.
+ *
+ * A `Timestamp` object can represent a maximum of ±8,640,000,000,000,000
+ * milliseconds, or ±100,000,000 (one hundred million) days, relative to the
+ * Unix epoch. This is the range from April 20, 271821 BC to September 13,
+ * 275760 AD.
+ *
+ * Unlike the Javascript built-in `Date` type, a `Timestamp` is immutable.
+ * Like a `Date`, a `Timestamp` object does not contain a timezone.
+ */
+export declare class Timestamp {
+    /** Number of milliseconds ellapsed since the Unix epoch. */
+    readonly unixMillis: number;
+    /**
+     * Returns a `Timestamp` representing the same moment in time as the given
+     * Javascript `Date` object.
+     *
+     * @throws if the given `Date` object has a timestamp value of NaN
+     */
+    static from(date: Date): Timestamp;
+    /**
+     * Creates a `Timestamp` object from a number of milliseconds from the Unix
+     * epoch.
+     *
+     * If the given number if outside the valid range (±8,640,000,000,000,000),
+     * this function will return `Timestamp.MAX` or `Timestamp.MIN` depending on
+     * the sign of the number.
+     *
+     * @throws if the given number is NaN
+     */
+    static fromUnixMillis(unixMillis: number): Timestamp;
+    /**
+     * Creates a `Timestamp` object from a number of seconds from the Unix epoch.
+     *
+     * If the given number if outside the valid range (±8,640,000,000,000), this
+     * function will return `Timestamp.MAX` or `Timestamp.MIN` depending on the
+     * sign of the number.
+     *
+     * @throws if the given number is NaN
+     */
+    static fromUnixSeconds(unixSeconds: number): Timestamp;
+    /**
+     * Parses a date in the date time string format.
+     *
+     * @throws if the given string is not a date in the date time string format
+     * @see https://tc39.es/ecma262/multipage/numbers-and-dates.html#sec-date-time-string-format
+     */
+    static parse(date: string): Timestamp;
+    /** Returns a `Timestamp` representing the current moment in time. */
+    static now(): Timestamp;
+    /** Thursday, 1 January 1970. */
+    static readonly UNIX_EPOCH: Timestamp;
+    /**
+     * Earliest moment in time representable as a `Timestamp`, namely April 20,
+     * 271821 BC.
+     *
+     * @see https://262.ecma-international.org/5.1/#sec-15.9.1.1
+     */
+    static readonly MIN: Timestamp;
+    /**
+     * Latest moment in time representable as a `Timestamp`, namely September 13,
+     * 275760 AD.
+     *
+     * @see https://262.ecma-international.org/5.1/#sec-15.9.1.1
+     */
+    static readonly MAX: Timestamp;
+    private constructor();
+    /** Number of seconds ellapsed since the Unix epoch. */
+    get unixSeconds(): number;
+    /**
+     * Returns a `Date` object representing the same moment in time as this
+     * `Timestamp`.
+     */
+    toDate(): Date;
+    toString(): string;
+}
+/** An immutable array of bytes. */
+export declare class ByteString {
+    private readonly arrayBuffer;
+    private readonly byteOffset;
+    /** The length of this byte string. */
+    readonly byteLength: number;
+    /**
+     * Returns an immutable byte string containing all the bytes of `input` from
+     * `start`, inclusive, up to `end`, exclusive.
+     *
+     * If `input` is an `ArrayBuffer`, this function copies the bytes. Otherwise
+     * this function returns a sliced view of the input `ByteString`.
+     *
+     * @example <caption>Copy an array buffer into a byte string</caption>
+     * const byteString = ByteString.sliceOf(arrayBuffer);
+     */
+    static sliceOf(input: ArrayBuffer | SharedArrayBuffer | ByteString, start?: number, end?: number): ByteString;
+    /**
+     * Decodes a Base64 string, which can be obtained by calling `toBase64()`.
+     *
+     * @throws if the given string is not a valid Base64 string.
+     * @see https://en.wikipedia.org/wiki/Base64
+     */
+    static fromBase64(base64: string): ByteString;
+    /**
+     * Decodes a hexadecimal string, which can be obtained by calling
+     * `toBase16()`.
+     *
+     * @throws if the given string is not a valid Base64 string.
+     */
+    static fromBase16(base16: string): ByteString;
+    /** An empty byte string. */
+    static readonly EMPTY: ByteString;
+    /** Copies the contents of this byte string into the given array buffer. */
+    copyTo(target: ArrayBuffer, targetOffset?: number): void;
+    /** Copies the contents of this byte string into a new array buffer. */
+    toBuffer(): ArrayBuffer;
+    /**
+     * Encodes this byte string into a Base64 string.
+     *
+     * @see https://en.wikipedia.org/wiki/Base64
+     */
+    toBase64(): string;
+    /** Encodes this byte string into a hexadecimal string. */
+    toBase16(): string;
+    at(index: number): number | undefined;
+    toString(): string;
+    private constructor();
+    private readonly uint8Array;
+}
+/** A read-only JSON value. */
+export type Json = null | boolean | number | string | readonly Json[] | Readonly<{
+    [name: string]: Json;
+}>;
+/**
+ * Resolves to the generated mutable class for a struct.
+ * The type parameter is the generated frozen class.
+ */
+export type MutableForm<Frozen> = Frozen extends _FrozenBase ? ReturnType<Frozen["toMutable"]> & Freezable<Frozen> : Freezable<Frozen>;
+/** Result of encoding a struct using binary encoding format. */
+export interface BinaryForm {
+    /** Length (in bytes) of the binary form. */
+    readonly byteLength: number;
+    /** Copies the contents of the binary form into the given array buffer. */
+    copyTo(target: ArrayBuffer, offset?: number): void;
+    /** Copies the contents of this byte string into a new array buffer. */
+    toBuffer(): ArrayBuffer;
+}
+/**
+ * When using the JSON serialization format, you can chose between two flavors.
+ *
+ * The dense flavor is the default flavor and is preferred in most cases.
+ * Structs are converted to JSON arrays, where the number of each field
+ * corresponds to the index of the value in the array. This results in a more
+ * compact representation than when using JSON objects, and this makes
+ * serialization and deserialization a bit faster. Because field names are left
+ * out of the JSON, it is a representation which allows persistence: you can
+ * safely rename a field in a '.skir' file without breaking backwards
+ * compatibility.
+ * One con of this representation is that it is harder to tell, just by looking
+ * at the JSON, what field of the struct each value in the array corresponds to.
+ *
+ * When using the readable flavor, structs are converted to JSON objects. The
+ * name of each field in the '.skir' file is used as-is in the JSON. This
+ * results in a representation which is much more readable by humans, but also
+ * not suited for persistence: when you rename a field in a '.skir' file, you
+ * will no lonnger be able to deserialize old JSONs.
+ *
+ * @example
+ * const jane = Person.create({firstName: "Jane", lastName: "Doe"});
+ *
+ * console.log(Person.serializer.toJson(jane, "dense"));
+ * // Output: ["Jane","Doe"]
+ *
+ * console.log(Person.serializer.toJson(jane));
+ * // Output: ["Jane","Doe"]
+ *
+ * console.log(Person.serializer.toJson(jane, "readable"));
+ * // Output: {
+ * //   "firstName": "Jane",
+ * //   "lastName": "Doe"
+ * // }
+ */
+export type JsonFlavor = "dense" | "readable";
+/**
+ * Serializes and deserializes instances of `T`. Supports two serialization
+ * formats: JSON and binary.
+ *
+ * All deserialization methods return a deeply-immutable `T`. If `T` is the
+ * generated frozen class for a struct, all serialization methods accept either
+ * a `T` or a `T.Mutable`.
+ *
+ * Do NOT create your own `Serializer` implementation. Only use implementations
+ * provided by Skir.
+ *
+ * @example
+ * let jane = Person.create({firstName: "Jane", lastName: "Doe"});
+ * const json = Person.serializer.toJson(jane);
+ * jane = Person.serializer.fromJson(json);
+ * expect(jane.firstName).toBe("Jane");
+ */
+export interface Serializer<T> {
+    /**
+     * Converts back the given stringified JSON to `T`.
+     * Works with both [flavors]{@link JsonFlavor} of JSON.
+     *
+     * Pass in "keep-unrecognized-values" if and only if the input JSON comes
+     * from a trusted program which might have been built from more recent
+     * source files.
+     */
+    fromJsonCode(code: string, keep?: "keep-unrecognized-values"): T;
+    /**
+     * Converts back the given JSON to `T`.
+     * Works with both [flavors]{@link JsonFlavor} of JSON.
+     *
+     * Pass in "keep-unrecognized-values" if and only if the input JSON comes
+     * from a trusted program which might have been built from more recent
+     * source files.
+     */
+    fromJson(json: Json, keep?: "keep-unrecognized-values"): T;
+    /**
+     * Converts back the given binary form to `T`.
+     *
+     * Pass in "keep-unrecognized-values" if and only if the input JSON comes
+     * from a trusted program which might have been built from more recent
+     * source files.
+     */
+    fromBytes(bytes: ArrayBuffer, keep?: "keep-unrecognized-values"): T;
+    /**
+     * Converts the given `T` to JSON and returns the stringified JSON. Same as
+     * calling `JSON.stringify()` on the result of `toJson()`.
+     *
+     * @param flavor dense or readable, defaults to dense
+     * @see JsonFlavor
+     */
+    toJsonCode(input: T | MutableForm<T>, flavor?: JsonFlavor): string;
+    /**
+     * Converts the given `T` to JSON. If you only need the stringified JSON, call
+     * `toJsonCode()` instead.
+     *
+     * @param flavor dense or readable, defaults to dense
+     * @see JsonFlavor
+     */
+    toJson(input: T | MutableForm<T>, flavor?: JsonFlavor): Json;
+    /** Converts the given `T` to binary format. */
+    toBytes(input: T | MutableForm<T>): BinaryForm;
+    /** An object describing the type `T`. Enables reflective programming. */
+    typeDescriptor: TypeDescriptorSpecialization<T>;
+}
+/**
+ * Returns a serializer of instances of the given Skir primitive type.
+ *
+ * @example
+ * expect(
+ *   primitiveSerializer("string").toJsonCode("foo")
+ * ).toBe(
+ *   '"foo"'
+ * );
+ */
+export declare function primitiveSerializer<P extends keyof PrimitiveTypes>(primitiveType: P): Serializer<PrimitiveTypes[P]>;
+/**
+ * Returns a serializer of arrays of `Item`s.
+ *
+ * @example
+ * expect(
+ *   arraySerializer(User.serializer).toJsonCode([JANE, JOE])
+ * ).toBe(
+ *   '[["jane"],["joe"]]'
+ * );
+ */
+export declare function arraySerializer<Item>(item: Serializer<Item>, keyChain?: string): Serializer<ReadonlyArray<Item>>;
+/** Returns a serializer of nullable `T`s. */
+export declare function optionalSerializer<T>(other: Serializer<T>): Serializer<T | null>;
+/**
+ * Describes the type `T`, where `T` is the TypeScript equivalent of a Skir
+ * type. Enables reflective programming.
+ *
+ * Every `TypeDescriptor` instance has a `kind` field which can take one of
+ * these 5 values: `"primitive"`, `"optional"`, `"array"`, `"struct"`, `"enum"`.
+ */
+export type TypeDescriptor<T = unknown> = OptionalDescriptor<T> | ArrayDescriptor<T> | StructDescriptor<T> | EnumDescriptor<T> | PrimitiveDescriptor;
+/** Specialization of `TypeDescriptor<T>` when `T` is known. */
+export type TypeDescriptorSpecialization<T> = [
+    T
+] extends [_FrozenBase] ? StructDescriptor<T> : [T] extends [_EnumBase] ? EnumDescriptor<T> : TypeDescriptor<T>;
+interface TypeDescriptorBase {
+    /** Returns the JSON representation of this `TypeDescriptor`. */
+    asJson(): Json;
+    /**
+     * Returns the JSON code representation of this `TypeDescriptor`.
+     * Same as calling `JSON.stringify()` on the result of `asJson()`.
+     */
+    asJsonCode(): string;
+    /**
+     * Converts from one serialized form to another.
+     *
+     * @example
+     * const denseJson = User.serializer.toJson(user, "dense");
+     * expect(
+     *   User.serializer.typeDescriptor.transform(denseJson, "readable")
+     * ).toMatch(
+     *   User.serializer.toJson(user, "readable")
+     * );
+     */
+    transform(json_or_bytes: Json | ArrayBuffer, out: JsonFlavor): Json;
+    transform(json: Json, out: "bytes"): ArrayBuffer;
+    transform(json_or_bytes: Json | ArrayBuffer, out: JsonFlavor | "bytes"): Json | ArrayBuffer;
+}
+/** Describes a primitive Skir type. */
+export interface PrimitiveDescriptor extends TypeDescriptorBase {
+    kind: "primitive";
+    primitive: keyof PrimitiveTypes;
+}
+/**
+ * An interface mapping a primitive Skir type to the corresponding TypeScript
+ * type.
+ */
+export interface PrimitiveTypes {
+    bool: boolean;
+    int32: number;
+    int64: bigint;
+    hash64: bigint;
+    float32: number;
+    float64: number;
+    timestamp: Timestamp;
+    string: string;
+    bytes: ByteString;
+}
+/**
+ * Describes an optional type. In a '.skir' file, an optional type is
+ * represented with a question mark at the end of another type.
+ */
+export interface OptionalDescriptor<T> extends TypeDescriptorBase {
+    readonly kind: "optional";
+    /** Describes the other (non-optional) type. */
+    readonly otherType: TypeDescriptor<NonNullable<T>>;
+}
+/** Describes an array type. */
+export interface ArrayDescriptor<T> extends TypeDescriptorBase {
+    readonly kind: "array";
+    /** Describes the type of the array items. */
+    readonly itemType: TypeDescriptor<T extends ReadonlyArray<infer Item> ? Item : unknown>;
+    readonly keyChain?: string;
+}
+/**
+ * Describes a Skir struct.
+ * The type parameter `T` refers to the generated frozen class for the struct.
+ */
+export interface StructDescriptor<T = unknown> extends TypeDescriptorBase {
+    readonly kind: "struct";
+    /** Name of the struct as specified in the '.skir' file. */
+    readonly name: string;
+    /**
+     * A string containing all the names in the hierarchic sequence above and
+     * including the struct. For example: "Foo.Bar" if "Bar" is nested within a
+     * type called "Foo", or simply "Bar" if "Bar" is defined at the top-level of
+     * the module.
+     */
+    readonly qualifiedName: string;
+    /**
+     * Path to the module where the struct is defined, relative to the root of the
+     * project.
+     */
+    readonly modulePath: string;
+    /**
+     * If the struct is nested within another type, the descriptor for that type.
+     * Undefined if the struct is defined at the top-level of the module.
+     */
+    readonly parentType: StructDescriptor | EnumDescriptor | undefined;
+    /** The fields of the struct in the order they appear in the '.skir' file. */
+    readonly fields: ReadonlyArray<StructField<T>>;
+    /** The field numbers marked as removed. */
+    readonly removedNumbers: ReadonlySet<number>;
+    /**
+     * Looks up a field. The key can be one of: the field name (e.g. "user_id");
+     * the name of the property in the generated class (e.g. "userId"), the field
+     * number.
+     *
+     * The return type is `StructField<T> | undefined` unless the key is known at
+     * compile-time to be the name of the property in the generated class, in
+     * which case it is `StructField<T>`.
+     */
+    getField<K extends string | number>(key: K): StructFieldResult<T, K>;
+    /**
+     * Returns a new instance of the generated mutable class for a struct.
+     * Performs a shallow copy of `initializer` if `initializer` is specified.
+     */
+    newMutable(initializer?: T | MutableForm<T>): MutableForm<T>;
+}
+/** Field of a Skir struct. */
+export interface StructField<Struct = unknown, Value = unknown> {
+    /** Field name as specified in the '.skir' file, e.g. "user_id". */
+    readonly name: string;
+    /** Name of the property in the generated class, e.g. "userId". */
+    readonly property: string;
+    /** Field number. */
+    readonly number: number;
+    /** Describes the field type. */
+    readonly type: TypeDescriptor<Value>;
+    /**
+     * Documentation for this struct field, specified as doc comments in the
+     * '.skir' file. May be empty.
+     */
+    doc: string;
+    /** Extracts the value of the field from the given struct. */
+    get(struct: Struct | MutableForm<Struct>): Value;
+    /** Assigns the given value to the field of the given struct. */
+    set(struct: MutableForm<Struct>, value: Value): void;
+}
+/**
+ * Return type of the `StructDescriptor.getField` method. If the argument is
+ * known at compile-time to be the name of a property of the generated class,
+ * resolves to `StructField<Struct>`. Otherwise, resolves to
+ * `StructField<Struct> | undefined`.
+ *
+ * @example <caption>The field is kown at compile-time</caption>
+ * const fieldNumber: number =
+ *   User.serializer.typeDescriptor.getField("userId").number;
+ *
+ * @example <caption>The field is not kown at compile-time</caption>
+ * const fieldNumber: number | undefined =
+ *   User.serializer.typeDescriptor.getField(variable)?.number;
+ */
+export type StructFieldResult<Struct, Key extends string | number> = StructField<Struct> | (Struct extends _FrozenBase ? Key extends keyof NonNullable<Struct[typeof _INITIALIZER]> ? never : undefined : undefined);
+/** Describes a Skir enum. */
+export interface EnumDescriptor<T = unknown> extends TypeDescriptorBase {
+    readonly kind: "enum";
+    /** Name of the enum as specified in the '.skir' file. */
+    readonly name: string;
+    /**
+     * A string containing all the names in the hierarchic sequence above and
+     * including the enum. For example: "Foo.Bar" if "Bar" is nested within a type
+     * called "Foo", or simply "Bar" if "Bar" is defined at the top-level of the
+     * module.
+     */
+    readonly qualifiedName: string;
+    /**
+     * Path to the module where the enum is defined, relative to the root of the
+     * project.
+     */
+    readonly modulePath: string;
+    /**
+     * If the enum is nested within another type, the descriptor for that type.
+     * Undefined if the struct is defined at the top-level of the module.
+     */
+    readonly parentType: StructDescriptor | EnumDescriptor | undefined;
+    /**
+     * Includes the UNKNOWN variant, followed by the other variants in the order
+     * they appear in the '.skir' file.
+     */
+    readonly variants: ReadonlyArray<EnumVariant<T>>;
+    /** The variant numbers marked as removed. */
+    readonly removedNumbers: ReadonlySet<number>;
+    /**
+     * Looks up a variant. The key can be one of the variant name or the variant
+     * number.
+     *
+     * The return type is `EnumVariant<T> | undefined` unless the key is known at
+     * compile-time to be a variant name of the enum, in which case it is
+     * `EnumVariant<T>`.
+     */
+    getVariant<K extends string | number>(key: K): EnumVariantResult<T, K>;
+}
+/**
+ * Variant of a Skir enum. Variants which don't hold any value are called
+ * constant variants. Their name is always in UPPER_CASE. Variants which hold
+ * value of a given type are called wrapper variants, and their name is always
+ * in lower_case.
+ */
+export type EnumVariant<Enum = unknown> = EnumConstantVariant<Enum> | EnumWrapperVariant<Enum, unknown>;
+/** Constant variant of a Skir enum. */
+export interface EnumConstantVariant<Enum = unknown> {
+    /**
+     * Variant name as specified in the '.skir' file, e.g. "MONDAY".
+     * Always in UPPER_CASE format.
+     */
+    readonly name: string;
+    /** Variant number. */
+    readonly number: number;
+    /** The instance of the generated class which corresponds to this variant. */
+    readonly constant: Enum;
+    /** Always undefined, unlike the `type` field of `EnumWrapperVariant`. */
+    readonly type?: undefined;
+    /**
+     * Documentation for this enum variant, specified as doc comments in the
+     * '.skir' file. May be empty.
+     */
+    readonly doc: string;
+}
+/** Wrapper variant of a Skir enum. */
+export interface EnumWrapperVariant<Enum = unknown, Value = unknown> {
+    /**
+     * Variant name as specified in the '.skir' file, e.g. "v4".
+     * Always in lower_case format.
+     */
+    readonly name: string;
+    /** Variant number. */
+    readonly number: number;
+    /** Describes the type of the value held by the variant. */
+    readonly type: TypeDescriptor<Value>;
+    /** Always undefined, unlike the `type` field of `EnumConstantVariant`. */
+    readonly constant?: undefined;
+    /**
+     * Documentation for this enum variant, specified as doc comments in the
+     * '.skir' file. May be empty.
+     */
+    readonly doc: string;
+    /**
+     * Extracts the value held by the given enum instance if it matches this
+     * enum variant. Returns undefined otherwise.
+     */
+    get(e: Enum): Value | unknown;
+    /**
+     * Returns a new enum instance matching this enum variant and holding the
+     * given value.
+     */
+    wrap(value: Value): Enum;
+}
+/**
+ * Return type of the `EnumDescriptor.getVariant` method. If the argument is
+ * known at compile-time to be the name of variant, resolves to
+ * `EnumVariant<Enum>`. Otherwise, resolves to
+ * `EnumVariant<Struct> | undefined`.
+ *
+ * @example <caption>The variant is known at compile-time</caption>
+ * const variantNumber: number =
+ *   Weekday.serializer.typeDescriptor.getVariant("MONDAY").number;
+ *
+ * @example <caption>The variant is not known at compile-time</caption>
+ * const variantNumber: number | undefined =
+ *   Weekday.serializer.typeDescriptor.getVariant(variable)?.number;
+ */
+export type EnumVariantResult<Enum, Key extends string | number> = EnumVariant<Enum> | (Enum extends _EnumBase ? Key extends Enum["union"]["kind"] ? never : undefined : undefined);
+/**
+ * Identifies a procedure (the "P" in "RPC") on both the client side and the
+ * server side.
+ */
+export interface Method<Request, Response> {
+    /** Name of the procedure as specified in the '.skir' file. */
+    name: string;
+    /**
+     * A number which uniquely identifies this procedure.
+     * When it is not specified in the '.skir' file, it is obtained by hashing the
+     * procedure name.
+     */
+    number: number;
+    /** Serializer of request objects. */
+    requestSerializer: Serializer<Request>;
+    /** Serializer of response objects. */
+    responseSerializer: Serializer<Response>;
+    /**
+     * Documentation for this procedure, specified as doc comments in the '.skir'
+     * file. May be empty.
+     */
+    doc: string;
+}
+/**
+ * Interface implemented by both the frozen and mutable classes generated for a
+ * struct. `T` is always the generated frozen class.
+ */
+export interface Freezable<T> {
+    /**
+     * Returns a deeply-immutable object, either by making a copy of `this` if
+     * `this` is mutable, or by returning `this` as-is if `this` is already
+     * immutable.
+     */
+    toFrozen(): T;
+}
+/**
+ * Returns a `TypeDescriptor` from its JSON representation as returned by
+ * `asJson()`.
+ */
+export declare function parseTypeDescriptorFromJson(json: Json): TypeDescriptor;
+/**
+ * Returns a `TypeDescriptor` from its JSON code representation as returned by
+ * `asJsonCode()`.
+ */
+export declare function parseTypeDescriptorFromJsonCode(code: string): TypeDescriptor;
+declare class UnrecognizedEnum {
+    readonly token: symbol;
+    readonly json?: Json | undefined;
+    readonly bytes?: ByteString | undefined;
+    constructor(token: symbol, json?: Json | undefined, bytes?: ByteString | undefined);
+}
+export declare const _EMPTY_ARRAY: readonly never[];
+export declare function _toFrozenArray<T, Initializer>(initializers: readonly Initializer[], itemToFrozenFn?: (item: Initializer) => T): readonly T[];
+export declare const _INITIALIZER: unique symbol;
+export declare abstract class _FrozenBase {
+    protected constructor(privateKey: symbol);
+    toMutable(): unknown;
+    toFrozen(): this;
+    toString(): string;
+    [_INITIALIZER]: unknown;
+}
+export declare abstract class _EnumBase {
+    protected constructor(privateKey: symbol, kind: string, value: unknown, unrecognized?: UnrecognizedEnum);
+    readonly union: {
+        kind: unknown;
+        value: unknown;
+    };
+    toString(): string;
+}
+/** Metadata of an HTTP request sent by a service client. */
+export type RequestMeta = Omit<RequestInit, "body" | "method">;
+/** Wire format used for SkirRPC HTTP request and response bodies. */
+export type TransportCodec = "legacy" | "cbor";
+/** Configuration options for a SkirRPC service client. */
+export interface ServiceClientOptions {
+    /**
+     * Codec used for RPC request and response bodies.
+     *
+     * Defaults to `legacy`, which preserves the original Skir colon-separated
+     * request body and JSON response body.
+     */
+    transportCodec?: TransportCodec;
+}
+export type RawRequestBody = string | Uint8Array | ArrayBuffer;
+/** Sends RPCs to a SkirRPC service. */
+export declare class ServiceClient {
+    private readonly serviceUrl;
+    private readonly getRequestMetadata;
+    private readonly options;
+    constructor(serviceUrl: string, getRequestMetadata?: (m: Method<unknown, unknown>) => Promise<RequestMeta> | RequestMeta, options?: ServiceClientOptions);
+    /** Invokes the given method on the remote server through an RPC. */
+    invokeRemote<Request, Response>(method: Method<Request, Response>, request: Request, httpMethod?: "GET" | "POST"): Promise<Response>;
+}
+/** Raw response returned by the server. */
+export interface RawResponse {
+    readonly data: string | Uint8Array;
+    readonly statusCode: number;
+    readonly contentType: string;
+}
+/**
+ * If this error is thrown from a method implementation, the specified status
+ * code and message will be returned in the HTTP response.
+ *
+ * If any other type of exception is thrown, the response status code will be
+ * 500 (Internal Server Error).
+ */
+export declare class ServiceError extends Error {
+    private readonly spec;
+    constructor(spec: {
+        statusCode: 400;
+        desc: "Bad Request";
+        message?: string;
+    } | {
+        statusCode: 401;
+        desc: "Unauthorized";
+        message?: string;
+    } | {
+        statusCode: 402;
+        desc: "Payment Required";
+        message?: string;
+    } | {
+        statusCode: 403;
+        desc: "Forbidden";
+        message?: string;
+    } | {
+        statusCode: 404;
+        desc: "Not Found";
+        message?: string;
+    } | {
+        statusCode: 405;
+        desc: "Method Not Allowed";
+        message?: string;
+    } | {
+        statusCode: 406;
+        desc: "Not Acceptable";
+        message?: string;
+    } | {
+        statusCode: 407;
+        desc: "Proxy Authentication Required";
+        message?: string;
+    } | {
+        statusCode: 408;
+        desc: "Request Timeout";
+        message?: string;
+    } | {
+        statusCode: 409;
+        desc: "Conflict";
+        message?: string;
+    } | {
+        statusCode: 410;
+        desc: "Gone";
+        message?: string;
+    } | {
+        statusCode: 411;
+        desc: "Length Required";
+        message?: string;
+    } | {
+        statusCode: 412;
+        desc: "Precondition Failed";
+        message?: string;
+    } | {
+        statusCode: 413;
+        desc: "Content Too Large";
+        message?: string;
+    } | {
+        statusCode: 414;
+        desc: "URI Too Long";
+        message?: string;
+    } | {
+        statusCode: 415;
+        desc: "Unsupported Media Type";
+        message?: string;
+    } | {
+        statusCode: 416;
+        desc: "Range Not Satisfiable";
+        message?: string;
+    } | {
+        statusCode: 417;
+        desc: "Expectation Failed";
+        message?: string;
+    } | {
+        statusCode: 418;
+        desc: "I'm a teapot";
+        message?: string;
+    } | {
+        statusCode: 421;
+        desc: "Misdirected Request";
+        message?: string;
+    } | {
+        statusCode: 422;
+        desc: "Unprocessable Content";
+        message?: string;
+    } | {
+        statusCode: 423;
+        desc: "Locked";
+        message?: string;
+    } | {
+        statusCode: 424;
+        desc: "Failed Dependency";
+        message?: string;
+    } | {
+        statusCode: 425;
+        desc: "Too Early";
+        message?: string;
+    } | {
+        statusCode: 426;
+        desc: "Upgrade Required";
+        message?: string;
+    } | {
+        statusCode: 428;
+        desc: "Precondition Required";
+        message?: string;
+    } | {
+        statusCode: 429;
+        desc: "Too Many Requests";
+        message?: string;
+    } | {
+        statusCode: 431;
+        desc: "Request Header Fields Too Large";
+        message?: string;
+    } | {
+        statusCode: 451;
+        desc: "Unavailable For Legal Reasons";
+        message?: string;
+    } | {
+        statusCode: 500;
+        desc: "Internal Server Error";
+        message?: string;
+    } | {
+        statusCode: 501;
+        desc: "Not Implemented";
+        message?: string;
+    } | {
+        statusCode: 502;
+        desc: "Bad Gateway";
+        message?: string;
+    } | {
+        statusCode: 503;
+        desc: "Service Unavailable";
+        message?: string;
+    } | {
+        statusCode: 504;
+        desc: "Gateway Timeout";
+        message?: string;
+    } | {
+        statusCode: 505;
+        desc: "HTTP Version Not Supported";
+        message?: string;
+    } | {
+        statusCode: 506;
+        desc: "Variant Also Negotiates";
+        message?: string;
+    } | {
+        statusCode: 507;
+        desc: "Insufficient Storage";
+        message?: string;
+    } | {
+        statusCode: 508;
+        desc: "Loop Detected";
+        message?: string;
+    } | {
+        statusCode: 510;
+        desc: "Not Extended";
+        message?: string;
+    } | {
+        statusCode: 511;
+        desc: "Network Authentication Required";
+        message?: string;
+    });
+    toRawResponse(): RawResponse;
+}
+export interface RequestHandler<RequestMeta = ExpressRequest> {
+    /**
+     * Parses the content of a user request and invokes the appropriate method.
+     * If you are using ExpressJS as your web application framework, you don't
+     * need to call this method, you can simply call the
+     * `installServiceOnExpressApp()` top-level function.
+     *
+     * If the request is a GET request, pass in the decoded query string as the
+     * request's body. The query string is the part of the URL after '?', and it
+     * can be decoded with DecodeURIComponent.
+     */
+    handleRequest(reqBody: RawRequestBody, reqMeta: RequestMeta): Promise<RawResponse>;
+}
+/** Configuration options for a SkirRPC service. */
+export interface ServiceOptions<RequestMeta = ExpressRequest> {
+    /**
+     * Codec used for RPC request and response bodies.
+     *
+     * Defaults to `legacy`, which accepts the original Skir colon-separated
+     * string and JSON-object request formats and returns JSON responses.
+     */
+    transportCodec: TransportCodec;
+    /**
+     * Whether to keep unrecognized values when deserializing requests.
+     *
+     * **WARNING:** Only enable this for data from trusted sources. Malicious
+     * actors could inject fields with IDs not yet defined in your schema. If you
+     * preserve this data and later define those IDs in a future schema version,
+     * the injected data could be deserialized as valid fields, leading to
+     * security vulnerabilities or data corruption.
+     *
+     * Defaults to `false`.
+     */
+    keepUnrecognizedValues: boolean;
+    /**
+     * Whether the message of an unknown error (i.e. not a `ServiceError`) can be
+     * sent to the client in the response body, which can help with debugging.
+     *
+     * By default, unknown errors are masked and the client receives a generic
+     * 'server error' message with status 500. This is to prevent leaking
+     * sensitive information to the client.
+     *
+     * You can enable this if your server is internal or if you are sure that your
+     * error messages are safe to expose. By passing a predicate instead of true
+     * or false, you can control on a per-error basis whether to expose the error
+     * message; for example, you can send error messages only if the user is an
+     * admin.
+     *
+     * Defaults to `false`.
+     */
+    canSendUnknownErrorMessage: boolean | ((errorInfo: MethodErrorInfo<RequestMeta, unknown>) => boolean);
+    /**
+     * Callback invoked whenever an error is thrown during method execution.
+     *
+     * Use this to log errors for monitoring, debugging, or alerting purposes.
+     *
+     * Defaults to function which logs the method name and error message via
+     * `console.error()`.
+     */
+    errorLogger: (errorInfo: MethodErrorInfo<RequestMeta, unknown>) => void;
+    /**
+     * URL to the JavaScript file for the Skir Studio app.
+     *
+     * Skir Studio is a web interface for exploring and testing your SkirRPC service.
+     * It is served when the service receives a request at '${serviceUrl}?studio'.
+     */
+    studioAppJsUrl: string;
+}
+/**
+ * Information about an error thrown during the execution of a method on the
+ * server side.
+ */
+interface MethodErrorInfo<RequestMeta, Request> {
+    /** The error thrown during the execution of the method. */
+    readonly error: any;
+    readonly method: Method<Request, unknown>;
+    readonly request: Request;
+    /**
+     * Metadata coming from the HTTP headers of the request.
+     * Undefined if the error was thrown in the execution of the function passed
+     * to `withMetaTransformer()`.
+     */
+    readonly reqMeta: RequestMeta | undefined;
+}
+/**
+ * Implementation of a SkirRPC service.
+ *
+ * Usage: call `.addMethod()` to register methods, then install the service on
+ * an HTTP server either by:
+ *   - calling the `installServiceOnExpressApp()` top-level function if you are
+ *       using ExpressJS
+ *   - writing your own implementation of `installServiceOn*()` which calls
+ *       `.handleRequest()` if you are using another web application framework
+ *
+ * ## Handling Request Metadata
+ *
+ * The `RequestMeta` type parameter specifies what metadata (authentication,
+ * headers, etc.) your method implementations receive. There are two approaches:
+ *
+ * ### Approach 1: Use the framework's request type directly
+ *
+ * Set `RequestMeta` to your framework's request type (e.g., `ExpressRequest`).
+ * All method implementations will receive the full framework request object.
+ *
+ * ```typescript
+ * const service = new Service<ExpressRequest>();
+ * service.addMethod(myMethod, async (req, expressReq) => {
+ *   const isAdmin = expressReq.user?.role === 'admin';
+ *   // ...
+ * });
+ * installServiceOnExpressApp(app, '/api', service, text, json);
+ * ```
+ *
+ * ### Approach 2: Use a simplified custom type
+ *
+ * Set `RequestMeta` to a minimal type containing only what your service needs.
+ * Use `withMetaTransformer()` to extract this data from the framework request
+ * when installing the service.
+ *
+ * ```typescript
+ * const service = new Service<{ isAdmin: boolean }>();
+ * service.addMethod(myMethod, async (req, { isAdmin }) => {
+ *   // Implementation is framework-agnostic and easy to unit test
+ *   if (!isAdmin) throw new ServiceError({ statusCode: 403, desc: "Forbidden" });
+ *   // ...
+ * });
+ *
+ * // Adapt to Express when installing
+ * const handler = service.withMetaTransformer((req: ExpressRequest) => ({
+ *   isAdmin: req.user?.role === 'admin'
+ * }));
+ * installServiceOnExpressApp(app, '/api', handler, text, json);
+ * ```
+ *
+ * This approach decouples your service from the HTTP framework, making it easier
+ * to test and clearer about what request data it actually uses.
+ */
+export declare class Service<RequestMeta = ExpressRequest> implements RequestHandler<RequestMeta> {
+    constructor(options?: Partial<ServiceOptions<RequestMeta>>);
+    addMethod<Request, Response>(method: Method<Request, Response>, impl: (req: Request, reqMeta: RequestMeta) => Promise<Response>): Service<RequestMeta>;
+    handleRequest(reqBody: RawRequestBody, reqMeta: RequestMeta): Promise<RawResponse>;
+    private doHandleRequest;
+    /**
+     * Creates a request handler that extracts simplified request metadata from
+     * framework-specific request objects before passing it to this service.
+     *
+     * This decouples your service implementation from the HTTP framework, making
+     * it easier to unit test (tests don't need to mock framework objects) and
+     * making the service implementation clearer by explicitly declaring exactly
+     * what request data it needs.
+     *
+     * @param transformFn Function that extracts the necessary data from the
+     *   framework-specific request object. Can be async or sync.
+     * @returns A request handler that accepts the framework-specific request type.
+     *
+     * @example
+     * ```typescript
+     * // Define a service that only needs to know if the user is an admin
+     *
+     * const service = new Service<{ isAdmin: boolean }>();
+     *
+     * service.addMethod(myMethod, async (req, { isAdmin }) => {
+     *   // Implementation is framework-agnostic and easy to test
+     *   if (!isAdmin) throw new ServiceError({ statusCode: 403, desc: "Forbidden" });
+     *   // ...
+     * });
+     *
+     * // Adapt it to work with Express
+     * const expressHandler = service.withMetaTransformer(
+     *   (req: ExpressRequest) => ({
+     *     isAdmin: req.user?.role === 'admin'
+     *   })
+     * );
+     * installServiceOnExpressApp(app, '/api', expressHandler, text, json);
+     * ```
+     */
+    withMetaTransformer<OriginalRequestMeta>(transformFn: (reqMeta: OriginalRequestMeta) => RequestMeta | Promise<RequestMeta>): RequestHandler<OriginalRequestMeta>;
+    private readonly options;
+    private readonly methodImpls;
+}
+export declare function installServiceOnExpressApp(app: ExpressApp, queryPath: string, service: RequestHandler<ExpressRequest>, text: typeof ExpressText, json: typeof ExpressJson, raw?: typeof ExpressRaw): void;
+interface StructSpec {
+    kind: "struct";
+    ctor: {
+        new (privateKey: symbol): unknown;
+    };
+    initFn: (target: unknown, initializer: unknown) => void;
+    name: string;
+    parentCtor?: {
+        new (): unknown;
+    };
+    doc?: string;
+    fields: readonly StructFieldSpec[];
+    removedNumbers?: readonly number[];
+}
+interface StructFieldSpec {
+    name: string;
+    property: string;
+    number: number;
+    type: TypeSpec;
+    doc?: string;
+    mutableGetter?: string;
+    indexable?: IndexableSpec;
+}
+interface IndexableSpec {
+    searchMethod: string;
+    keyFn: (v: unknown) => unknown;
+    keyToHashable?: (v: unknown) => unknown;
+}
+interface EnumSpec<Enum = unknown> {
+    kind: "enum";
+    ctor: {
+        new (privateKey: symbol, kind: string, value?: unknown, unrecognized?: UnrecognizedEnum): Enum;
+    };
+    createValueFn?: (initializer: unknown) => unknown;
+    name: string;
+    parentCtor?: {
+        new (): unknown;
+    };
+    doc?: string;
+    variants: EnumVariantSpec[];
+    removedNumbers?: readonly number[];
+}
+interface EnumVariantSpec {
+    name: string;
+    number: number;
+    type?: TypeSpec;
+    doc?: string;
+}
+type TypeSpec = {
+    kind: "optional";
+    other: TypeSpec;
+} | {
+    kind: "array";
+    item: TypeSpec;
+    keyChain?: string;
+} | {
+    kind: "record";
+    ctor: {
+        new (): unknown;
+    };
+} | {
+    kind: "primitive";
+    primitive: keyof PrimitiveTypes;
+};
+export declare function _initModuleClasses(modulePath: string, records: ReadonlyArray<StructSpec | EnumSpec>): void;
+export {};
+//# sourceMappingURL=skir-client.d.ts.map