# @imqueue/rpc 3.5.3 · API reference

Source: https://imqueue.org/api/rpc/latest/
Published: 2026-08-04
Author: @imqueue maintainers (https://github.com/imqueue)
Package: @imqueue/rpc 3.5.3 — generated reference, not hand-written

Type-safe RPC over a message queue — services, clients and the decorators that describe them, built on `@imqueue/core`.

Write a service by extending `IMQService` and marking each remotely callable method with `@expose()`. Complex argument and return types need a class-level `@classType()` (or `@indexed()`) plus `@property()` on each field. Then generate a typed client for that service with `IMQClient.create()`, which reads the running service's own description.

## Remarks

Decorator protocol. This package targets standard (TC39) decorators. Consuming projects must compile with `experimentalDecorators: false`, `removeComments: false`, and `esnext.decorators` in `lib`. The decorators still work under legacy compilation, but behaviour differs — see `classType`, which is required under standard decorators and a no-op under legacy, and `expose`, whose registration is deferred to first construction under standard decorators.

`removeComments: false` is not optional: standard decorators provide no runtime type reflection, so an exposed method's JSDoc is the only source of argument and return types for the generated client, and the documented `@param` list is what the service's argument-count check validates.

Importing this package installs a global `Symbol.metadata` polyfill, which standard decorator metadata depends on.

Re-exports. This package re-exports the entire `@imqueue/core` surface, so core types and helpers can be imported from either package. The one exception is core's default-exported `IMQ` factory: `export *` never forwards a default, so `import IMQ from '@imqueue/rpc'` yields `undefined` — import it from `@imqueue/core` directly.

## Example


```typescript
import { IMQService, IMQClient, expose } from '@imqueue/rpc';

class UserService extends IMQService {
    // NOTE: a real service needs a JSDoc block here with typed
    // @param / @returns tags — that is where the generated client
    // gets its types from
    @expose()
    public async count(active: boolean): Promise<number> {
        return 42;
    }
}

await new UserService().start();

// elsewhere — generates and loads a typed client
const ns = await IMQClient.create('UserService');
const client = new ns.UserClient();

await client.start();
console.log(await client.count(true));
```

## Classes


| Class | Description |
| --- | --- |
| [Description](https://imqueue.org/api/rpc/latest/rpc.description/) | The self-description a service serves to its clients, and the input to client generation. |
| [IMQCache](https://imqueue.org/api/rpc/latest/rpc.imqcache/) | Process-wide static registry of cache adapters. |
| [IMQDelay](https://imqueue.org/api/rpc/latest/rpc.imqdelay/) | Represents a delay expressed as a numeric timer value in a given time unit. Used to defer IMQ request processing. |
| [IMQLock](https://imqueue.org/api/rpc/latest/rpc.imqlock/) | In-process, promise-based locks used to collapse concurrent identical calls: the first caller executes the work while later callers for the same key wait and are then resolved with the first caller's result. |
| [IMQMetadata](https://imqueue.org/api/rpc/latest/rpc.imqmetadata/) | Arbitrary, JSON-serializable metadata bag carried alongside an IMQ request. Each property value must be a valid JSON value. |
| [IMQRPCDescription](https://imqueue.org/api/rpc/latest/rpc.imqrpcdescription/) | Process-global registry of RPC metadata gathered by the decorators. |
| [RedisCache](https://imqueue.org/api/rpc/latest/rpc.rediscache/) | Class RedisCache. Implements a cache engine on top of Redis. |


## Abstract Classes


| Abstract Class | Description |
| --- | --- |
| [IMQClient](https://imqueue.org/api/rpc/latest/rpc.imqclient/) | Base class for service clients. Subclass it and declare every remote method as `@remote() async m(...args) \{ return await this.remoteCall<T>(...arguments); \}`, or let [IMQClient.create()](https://imqueue.org/api/rpc/latest/rpc.imqclient.create/) generate the subclass from a running service's description. |
| [IMQService](https://imqueue.org/api/rpc/latest/rpc.imqservice/) | Class IMQService Basic abstract service (server-side) implementation |


## Functions


| Function | Description |
| --- | --- |
| [classType()](https://imqueue.org/api/rpc/latest/rpc.classtype/) | Registers a complex-type class's `@property` field definitions into the RPC type description, so the type can be exposed to service clients. |
| [currentMetadata()](https://imqueue.org/api/rpc/latest/rpc.currentmetadata/) | Returns the metadata of the in-flight IMQ request for the current async execution, if any. Returns `undefined` outside of a `runWithRequest()` scope. The transport carries metadata as an opaque bag; callers interpret its fields. |
| [expose()](https://imqueue.org/api/rpc/latest/rpc.expose/) | Makes a service method callable remotely by registering it in the RPC service description. |
| [imqCallRejector(reject, req, client)](https://imqueue.org/api/rpc/latest/rpc.imqcallrejector/) | Builds a call rejector that rejects the pending promise and then runs the optional after-call hook. |
| [imqCallResolver(resolve, req, client)](https://imqueue.org/api/rpc/latest/rpc.imqcallresolver/) | Builds a call resolver that resolves the pending promise and then runs the optional after-call hook. |
| [IMQError(code, message, stack, method, args, original)](https://imqueue.org/api/rpc/latest/rpc.imqerror/) | Builds a JSON representation of an IMQ error. |
| [indexed(indexTypedef)](https://imqueue.org/api/rpc/latest/rpc.indexed/) | Exposes a complex service type that carries an index signature. |
| [lock(enabledOrOptions)](https://imqueue.org/api/rpc/latest/rpc.lock/) | Creates a `@lock()` method decorator. Concurrent calls to the decorated method that share the same arguments are coalesced: only the first call is executed, and all the others resolve with its result. Call similarity is determined by the method's argument values. The returned decorator is dual-mode: it works both as a standard (TC39) and as a legacy method decorator. |
| [logged(options)](https://imqueue.org/api/rpc/latest/rpc.logged/) | Creates a `@logged()` method decorator that wraps the decorated method in a try/catch and logs any error it throws. The logger is resolved in this order: an explicitly passed logger, then a `logger` defined on the instance or on the class, and finally the global `console`. By default the error is re-thrown after being logged; pass `{ doNotThrow: true }` to swallow it. The returned decorator is dual-mode: it works both as a standard (TC39) and as a legacy method decorator. |
| [parseSourceComments(src, className)](https://imqueue.org/api/rpc/latest/rpc.parsesourcecomments/) | Extracts method JSDoc blocks from original source text of a given class. The text may be TypeScript (type annotations, generics, modifiers, decorators), which acorn cannot parse — so extraction is textual: the search is narrowed to the class region (from the class declaration to the next class declaration or EOF), and each doc block is attributed to the method whose declaration head immediately follows it. When several blocks precede a method, the closest one wins, matching the runtime parser. |
| [property(type, isOptional)](https://imqueue.org/api/rpc/latest/rpc.property/) | Marks a class field as part of an exposed complex type, so it is described to clients and appears in the generated client interfaces. |
| [registerType(ctor, metadata, indexType)](https://imqueue.org/api/rpc/latest/rpc.registertype/) | Flushes `@property` definitions collected on a class into the RPC type description. Invoked by class-level decorators once the class (and hence its name) is available. |
| [remote()](https://imqueue.org/api/rpc/latest/rpc.remote/) | Creates a `@remote()` method decorator for client classes. The decorated method has the remote method name appended to its arguments and is then forwarded to `remoteCall()`. The returned decorator is dual-mode: it works both as a standard (TC39) and as a legacy (experimentalDecorators) method decorator. |
| [runWithRequest(request, fn)](https://imqueue.org/api/rpc/latest/rpc.runwithrequest/) | Runs the given function with `request` bound to the current async execution context, so any code reached from it (and its asynchronous continuations) can access the in-flight request's metadata via `currentMetadata()` without threading it through call signatures. The binding is scoped to the function: it is established for the duration of the call and automatically removed afterwards, which keeps concurrent requests isolated from one another. |
| [send(request, response, service)](https://imqueue.org/api/rpc/latest/rpc.send/) | Sends IMQ response with support of after call optional hook |


## Interfaces


| Interface | Description |
| --- | --- |
| [ArgDescription](https://imqueue.org/api/rpc/latest/rpc.argdescription/) | Description of one argument of an exposed method, as parsed from its JSDoc. |
| [CacheDecorator](https://imqueue.org/api/rpc/latest/rpc.cachedecorator/) | The type of the [cache](https://imqueue.org/api/rpc/latest/rpc.cache/) export: a decorator factory that also carries process-wide defaults. |
| [CacheDecoratorOptions](https://imqueue.org/api/rpc/latest/rpc.cachedecoratoroptions/) | Per-method options for the [cache](https://imqueue.org/api/rpc/latest/rpc.cache/) decorator. |
| [ICache](https://imqueue.org/api/rpc/latest/rpc.icache/) | Generic cache adapter interface. Any cache engine implementation must conform to this contract to be usable within IMQ. |
| [ICacheConstructor](https://imqueue.org/api/rpc/latest/rpc.icacheconstructor/) | Constructor signature the registry uses to instantiate a cache adapter class. |
| [IMQAfterCall](https://imqueue.org/api/rpc/latest/rpc.imqaftercall/) | Hook invoked after a call has been handled. |
| [IMQBeforeCall](https://imqueue.org/api/rpc/latest/rpc.imqbeforecall/) | Hook invoked before a call is dispatched. |
| [IMQClientOptions](https://imqueue.org/api/rpc/latest/rpc.imqclientoptions/) | Options accepted by a generated IMQ client. |
| [IMQLockMetadata](https://imqueue.org/api/rpc/latest/rpc.imqlockmetadata/) | Map from lock key to the metadata describing the call currently associated with that key. |
| [IMQLockMetadataItem](https://imqueue.org/api/rpc/latest/rpc.imqlockmetadataitem/) | Diagnostic description of a locked call. |
| [IMQMetricsServerOptions](https://imqueue.org/api/rpc/latest/rpc.imqmetricsserveroptions/) | Options for the built-in metrics server. |
| [IMQRPCError](https://imqueue.org/api/rpc/latest/rpc.imqrpcerror/) | Failure descriptor for a remote call. Produced by a service when a method throws, and also before dispatch when the method does not exist, is not exposed, or was called with the wrong number of arguments. A client additionally synthesizes one locally on call timeout. |
| [IMQRPCRequest](https://imqueue.org/api/rpc/latest/rpc.imqrpcrequest/) | Wire format of a remote call, produced by a client and consumed by a service. |
| [IMQRPCResponse](https://imqueue.org/api/rpc/latest/rpc.imqrpcresponse/) | Response message data structure that a service replies with to handled requests. |
| [IMQServiceOptions](https://imqueue.org/api/rpc/latest/rpc.imqserviceoptions/) | Options accepted by an IMQ service. |
| [IMQWrapCall](https://imqueue.org/api/rpc/latest/rpc.imqwrapcall/) | Around hook wrapping the actual service method invocation. It receives the request/response and a `next` callback that runs the method and resolves to its return value; it MUST call `next()` (returning its resolved value) to produce the response data. Unlike `beforeCall`/`afterCall`, this lets a hook run the method inside its own scope — e.g. establishing an OpenTelemetry context so any spans the method (and its downstream calls) create nest under the request span. When unset, the method is invoked directly. |
| [IRedisCacheOptions](https://imqueue.org/api/rpc/latest/rpc.irediscacheoptions/) | Options accepted by [RedisCache.init()](https://imqueue.org/api/rpc/latest/rpc.rediscache.init/). |
| [LockOptions](https://imqueue.org/api/rpc/latest/rpc.lockoptions/) | Options for the [lock()](https://imqueue.org/api/rpc/latest/rpc.lock/) decorator. |
| [LoggedDecoratorOptions](https://imqueue.org/api/rpc/latest/rpc.loggeddecoratoroptions/) | Options for the [logged()](https://imqueue.org/api/rpc/latest/rpc.logged/) decorator. |
| [MethodDescription](https://imqueue.org/api/rpc/latest/rpc.methoddescription/) | Description of one exposed method: its summary, its positional arguments and its return value. |
| [MethodsCollectionDescription](https://imqueue.org/api/rpc/latest/rpc.methodscollectiondescription/) | Map of method name to method description. |
| [PropertyDescription](https://imqueue.org/api/rpc/latest/rpc.propertydescription/) | Description of one property of an exposed complex type. |
| [ReturnValueDescription](https://imqueue.org/api/rpc/latest/rpc.returnvaluedescription/) | Description of an exposed method's return value, as parsed from its JSDoc. |
| [ServiceClassDescription](https://imqueue.org/api/rpc/latest/rpc.serviceclassdescription/) | The exposed methods a single class declares, plus its parent's name. |
| [ServiceDescription](https://imqueue.org/api/rpc/latest/rpc.servicedescription/) | Raw registry of every class that declares exposed methods, keyed by class name — the storage format behind [IMQRPCDescription.serviceDescription](https://imqueue.org/api/rpc/latest/rpc.imqrpcdescription.servicedescription/). |
| [Thunk](https://imqueue.org/api/rpc/latest/rpc.thunk/) | A zero-argument function whose return value is resolved lazily. Used by [property()](https://imqueue.org/api/rpc/latest/rpc.property/) and [indexed()](https://imqueue.org/api/rpc/latest/rpc.indexed/) so a type definition can reference a class that is not yet initialized at decoration time — self-references and forward references. |
| [TypeDescription](https://imqueue.org/api/rpc/latest/rpc.typedescription/) | The property bag of a single exposed type: property name to property description. |
| [TypesDescription](https://imqueue.org/api/rpc/latest/rpc.typesdescription/) | Every exposed complex type, keyed by class name. |


## Variables


| Variable | Description |
| --- | --- |
| [AFTER\_HOOK\_ERROR](https://imqueue.org/api/rpc/latest/rpc.after_hook_error/) | Prefix used when logging a failure inside an `afterCall` hook. |
| [BEFORE\_HOOK\_ERROR](https://imqueue.org/api/rpc/latest/rpc.before_hook_error/) | Prefix used when logging a failure inside a `beforeCall` hook. |
| [cache](https://imqueue.org/api/rpc/latest/rpc.cache/) | Creates a `@cache()` method decorator that memoizes the decorated method's result in a cache adapter (RedisCache by default). On each call the cache is checked first; on a miss the method runs, and its result is stored under a key derived from the class name, method name, and arguments. The returned decorator is dual-mode: it works both as a standard (TC39) and as a legacy method decorator. |
| [DEFAULT\_IMQ\_CLIENT\_OPTIONS](https://imqueue.org/api/rpc/latest/rpc.default_imq_client_options/) | Default options applied to every generated IMQ client: the core queue defaults, plus cleanup enabled with a `'*:client'` filter and the code-generation settings. |
| [DEFAULT\_IMQ\_METRICS\_SERVER\_OPTIONS](https://imqueue.org/api/rpc/latest/rpc.default_imq_metrics_server_options/) | Default metrics server options |
| [DEFAULT\_IMQ\_SERVICE\_OPTIONS](https://imqueue.org/api/rpc/latest/rpc.default_imq_service_options/) | Default options applied to every IMQ service: the core queue defaults, plus cleanup enabled with a `'*:client'` filter, single-process mode, and one worker per core. |
| [DEFAULT\_REDIS\_CACHE\_OPTIONS](https://imqueue.org/api/rpc/latest/rpc.default_redis_cache_options/) | Default options for [RedisCache](https://imqueue.org/api/rpc/latest/rpc.rediscache/): the standard queue defaults, with `prefix` overridden to `imq-cache` so cache keys never collide with queue keys under the `imq` prefix. |
| [REDIS\_CLIENT\_INIT\_ERROR](https://imqueue.org/api/rpc/latest/rpc.redis_client_init_error/) | Message of the `TypeError` thrown by any [RedisCache](https://imqueue.org/api/rpc/latest/rpc.rediscache/) operation invoked before a connection has been established. Exported so callers can match on it. |


## Type Aliases


| Type Alias | Description |
| --- | --- |
| [AcquiredLock](https://imqueue.org/api/rpc/latest/rpc.acquiredlock/) | What [IMQLock.acquire()](https://imqueue.org/api/rpc/latest/rpc.imqlock.acquire/) resolves to: the literal `true` when this caller acquired the lock and must perform the work, or the value the lock holder passed to [IMQLock.release()](https://imqueue.org/api/rpc/latest/rpc.imqlock.release/) when this caller had to wait. |
| [ICacheAdapter](https://imqueue.org/api/rpc/latest/rpc.icacheadapter/) | Accepted cache adapter references: a constructor, an instance, or an adapter name. |
| [IMQLockQueue](https://imqueue.org/api/rpc/latest/rpc.imqlockqueue/) | The FIFO queue of callers waiting on a single lock key, drained in arrival order when the lock is released. |
| [IMQLockTask](https://imqueue.org/api/rpc/latest/rpc.imqlocktask/) | Internal representation of one queued waiter: its promise's `[resolve, reject]` pair, selected by [IMQLock.release()](https://imqueue.org/api/rpc/latest/rpc.imqlock.release/) according to whether an error was supplied. |
| [LoggedLogLevel](https://imqueue.org/api/rpc/latest/rpc.loggedloglevel/) | Names of the `ILogger` methods [logged()](https://imqueue.org/api/rpc/latest/rpc.logged/) can use to record a caught error. |