EntityProxy

Derives RPC and HTTP API surfaces from clustered entities.

The generated APIs let callers use ordinary RPC clients or HTTP routes while the cluster runtime still locates and delivers messages to the entity instance identified by entityId. Each generated operation keeps the original payload and success schema, adds cluster client errors, and creates a discard variant for fire-and-forget delivery.

4 exports Added in v4.0.0 Source

Constructors

toHttpApiGroup

Added in v4.0.0 Source

Derives an HttpApiGroup from an Entity.

Signature

declare function toHttpApiGroup<Name extends string, Type extends string, Rpcs extends Any>(
  name: Name,
  entity: Entity<Type, Rpcs>,
): HttpApiGroup<Name, ConvertHttpApi<Rpcs>>;

toRpcGroup

Added in v4.0.0 Source

Derives an RpcGroup from an Entity.

Signature

declare function toRpcGroup<Type extends string, Rpcs extends Any>(
  entity: Entity<Type, Rpcs>,
): RpcGroup<ConvertRpcs<Rpcs, Type>>;

Converting

ConvertHttpApi type

Added in v4.0.0 Source

Type-level conversion used by toHttpApiGroup.

Details

For each entity RPC, this creates a POST endpoint at /<tag>/:entityId and a discard endpoint at /<tag>/:entityId/discard, including cluster client errors.

Signature

type ConvertHttpApi<Rpcs extends Rpc.Any> =
  Rpcs extends Rpc.Rpc<
    infer _Tag,
    infer _Payload,
    infer _Success,
    infer _Error,
    infer _Middleware,
    infer _Requires
  >
    ?
        | HttpApiEndpoint.HttpApiEndpoint<
            _Tag,
            "POST",
            `/${Lowercase<_Tag>}/:entityId`,
            Schema.Struct<{
              entityId: typeof EntityId;
            }>,
            never,
            _Payload,
            never,
            _Success,
            _Error | typeof MailboxFull | typeof AlreadyProcessingMessage | typeof PersistenceError
          >
        | HttpApiEndpoint.HttpApiEndpoint<
            `${_Tag}Discard`,
            "POST",
            `/${Lowercase<_Tag>}/:entityId/discard`,
            Schema.Struct<{
              entityId: typeof EntityId;
            }>,
            never,
            _Payload,
            never,
            Schema.Void,
            typeof MailboxFull | typeof AlreadyProcessingMessage | typeof PersistenceError
          >
    : never;

ConvertRpcs type

Added in v4.0.0 Source

Type-level conversion used by toRpcGroup.

Details

For each entity RPC, this creates a prefixed request RPC and a discard RPC whose payload includes entityId, and whose errors include cluster client errors.

Signature

type ConvertRpcs<Rpcs extends Rpc.Any, Prefix extends string> =
  Rpcs extends Rpc.Rpc<
    infer _Tag,
    infer _Payload,
    infer _Success,
    infer _Error,
    infer _Middleware,
    infer _Requires
  >
    ?
        | Rpc.Rpc<
            `${Prefix}.${_Tag}`,
            Schema.Struct<{
              entityId: typeof Schema.String;
              payload: _Payload;
            }>,
            _Success,
            Schema.Codec<
              _Error["Type"] | MailboxFull | AlreadyProcessingMessage | PersistenceError,
              | _Error["Encoded"]
              | (typeof MailboxFull)["Encoded"]
              | (typeof AlreadyProcessingMessage)["Encoded"]
              | (typeof PersistenceError)["Encoded"],
              _Error["DecodingServices"],
              _Error["EncodingServices"]
            >
          >
        | Rpc.Rpc<
            `${Prefix}.${_Tag}Discard`,
            Schema.Struct<{
              entityId: typeof Schema.String;
              payload: _Payload;
            }>,
            typeof Schema.Void,
            Schema.Union<
              [typeof MailboxFull, typeof AlreadyProcessingMessage, typeof PersistenceError]
            >
          >
    : never;