@pylonsync/functions 0.16.0 → 0.17.0

package/dist/index.d.ts

@@ -26,4 +26,4 @@ export type { WorkflowDefinition, WorkflowRun, WorkflowRunRequest, WorkflowRunne
 export { resetDb, installTestIsolation } from "./testing";
 export { slugifyName, availableSlug } from "./slugify";
 export type { SsrResponse, SsrCookieOptions, SsrMetadata, Sitemap, SitemapEntry, Robots, RobotsRule, } from "./ssr-runtime";
-export type { QueryCtx, MutationCtx, ActionCtx, DbReader, DbWriter, Stream, Scheduler, AuthInfo, AuthMode, AuthRequirement, FnDefinition, Validator, AnyValidator, ValidatorSchema, InferValidator, InferArgs, RequireMember, RequireMemberOptions, Shards, ShardsReader, ShardInfo, MemberRow, Workflows, VectorSearchQuery, VectorSearchResult, SearchResult, PaginationResult, Llm, LlmMessage, LlmContentBlock, LlmTool, LlmCompleteRequest, LlmCompleteResponse, LlmStreamEvent, Rooms, Domains, TenantDomainResult, TenantDomainDns, DomainAvailability, DomainContact, RegisterDomainOptions, RegisteredDomainResult, } from "./types";
+export type { QueryCtx, MutationCtx, ActionCtx, DbReader, DbWriter, Stream, Scheduler, AuthInfo, AuthMode, AuthRequirement, FnDefinition, Validator, AnyValidator, ValidatorSchema, InferValidator, InferArgs, RequireMember, RequireMemberOptions, Shards, ShardsReader, ShardsWriter, ShardInfo, ShardTransfer, MemberRow, Workflows, VectorSearchQuery, VectorSearchResult, SearchResult, PaginationResult, Llm, LlmMessage, LlmContentBlock, LlmTool, LlmCompleteRequest, LlmCompleteResponse, LlmStreamEvent, Rooms, Domains, TenantDomainResult, TenantDomainDns, DomainAvailability, DomainContact, RegisterDomainOptions, RegisteredDomainResult, } from "./types";

package/dist/types.d.ts

@@ -790,9 +790,63 @@ export interface Shards {
     get(shardId: string): Promise<ShardInfo | null>;
     /** Every running shard. */
     list(): Promise<ShardInfo[]>;
+    /**
+     * Move a player from shard `from` to shard `to` (a zone line, a dungeon,
+     * a match), possibly on another machine. The source module's
+     * `transfer_out` removes the player's entity and the target's
+     * `transfer_in` adds it, with its state. The player's connections get a
+     * transfer frame with a ticket for `to` (for the same user, with
+     * `opts.claims`), and the client libraries reconnect there. The target's
+     * `transfer_in` sees that ticket to decide. Actions only.
+     *
+     * On an error the player stays in `from`. Throws
+     * `SHARD_TRANSFER_REFUSED` when a module refuses,
+     * `SHARD_TRANSFER_NO_PLAYER` when `from` has no entity for the
+     * subscriber, `SHARD_TRANSFER_BUSY` while it is already moving,
+     * `SHARD_TRANSFER_UNSUPPORTED`, or `SHARD_NOT_FOUND`.
+     */
+    transfer(from: string, subscriberId: string, to: string, opts?: {
+        claims?: Record<string, unknown>;
+    }): Promise<ShardTransfer>;
+    /**
+     * Send a message to shards on any machine: `"shard:<id>"` for one,
+     * `"group:<name>"` for the shards whose module lists that group, `"all"`
+     * for every shard. The module's `on_message` gets `topic` and `data` as
+     * JSON bytes at the start of its next tick, with an empty sender. For a
+     * GM command, a realm-wide event, or a server-side alert. Actions only.
+     *
+     * Delivery is at most once: a shard that is stopped, busy (1024 messages
+     * waiting), or on a machine that cannot be reached, misses it. Throws
+     * `SHARD_MESSAGE_INVALID` for a bad target, an empty topic (at most 128
+     * bytes), or data over 64 KB.
+     */
+    publish(to: string, topic: string, data?: unknown): Promise<void>;
+    /**
+     * Send `input` to shard `shardId`, on any machine. The module's
+     * `apply_input` gets it on the shard's next tick, from the empty
+     * subscriber id (no connection can have it), in the shard's input
+     * format. For a GM command, or a keep claimed on the website.
+     *
+     * In a mutation the input is sent after the mutation commits, and not
+     * at all when it rolls back. Delivery is at most once: a shard that
+     * stops, a full input queue, or a machine that cannot be reached loses
+     * it. In an action, a shard on this machine has it when this resolves.
+     * Throws `SHARD_INPUT_INVALID` for a bad id or an input over 64 KB of
+     * JSON, and in an action `SHARD_NOT_FOUND` or `SHARD_BUSY`.
+     */
+    send(shardId: string, input: unknown): Promise<void>;
 }
-/** `ctx.shards` in a query or mutation: tickets and reads, no start or stop. */
+/** A finished `ctx.shards.transfer`. */
+export interface ShardTransfer {
+    /** The shard the player is in now. */
+    shard: string;
+    /** A ticket for it, which the transfer frame also carried. */
+    ticket: string;
+}
+/** `ctx.shards` in a query: tickets and reads, no start or stop. */
 export type ShardsReader = Pick<Shards, "ticket" | "get" | "list">;
+/** `ctx.shards` in a mutation: a query's, and inputs sent after the commit. */
+export type ShardsWriter = Pick<Shards, "ticket" | "get" | "list" | "send">;
 /** A running shard, from `ctx.shards.create`, `get`, or `list`. */
 export interface ShardInfo {
     id: string;
@@ -863,8 +917,8 @@ export interface MutationCtx<R extends AuthRequirement = "optional"> {
     workflows: Workflows;
     /** Signed file-download URLs — see {@link Files}. */
     files: Files;
-    /** Shard tickets and reads — see {@link Shards}. */
-    shards: ShardsReader;
+    /** Shard tickets, reads, and inputs after the commit — see {@link Shards}. */
+    shards: ShardsWriter;
     /** Create a typed error that triggers rollback. */
     error(code: string, message: string): Error;
     /** Assert org membership (optionally a role) — see {@link RequireMember}. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/index.ts

@@ -75,7 +75,9 @@ export type {
   RequireMemberOptions,
   Shards,
   ShardsReader,
+  ShardsWriter,
   ShardInfo,
+  ShardTransfer,
   MemberRow,
   Workflows,
   VectorSearchQuery,

package/src/runtime.ts

@@ -24,6 +24,7 @@ import type {
   Files,
   Shards,
   ShardInfo,
+  ShardTransfer,
   Stream,
   Scheduler,
   Llm,
@@ -555,6 +556,33 @@ function buildShards(callId: string): Shards {
     async list() {
       return rpc(callId, { type: "shard_op", op: "list" }) as Promise<ShardInfo[]>;
     },
+    async publish(to, topic, data) {
+      await rpc(callId, {
+        type: "shard_op",
+        op: "publish",
+        to,
+        topic,
+        params: data ?? null,
+      });
+    },
+    async send(shardId, input) {
+      await rpc(callId, {
+        type: "shard_op",
+        op: "send",
+        id: shardId,
+        params: input ?? null,
+      });
+    },
+    async transfer(from, subscriberId, to, opts) {
+      return rpc(callId, {
+        type: "shard_op",
+        op: "transfer",
+        id: from,
+        subscriber: subscriberId,
+        to,
+        claims: opts?.claims ?? null,
+      }) as Promise<ShardTransfer>;
+    },
   };
 }
 

package/src/types.ts

@@ -892,11 +892,73 @@ export interface Shards {
 
   /** Every running shard. */
   list(): Promise<ShardInfo[]>;
+
+  /**
+   * Move a player from shard `from` to shard `to` (a zone line, a dungeon,
+   * a match), possibly on another machine. The source module's
+   * `transfer_out` removes the player's entity and the target's
+   * `transfer_in` adds it, with its state. The player's connections get a
+   * transfer frame with a ticket for `to` (for the same user, with
+   * `opts.claims`), and the client libraries reconnect there. The target's
+   * `transfer_in` sees that ticket to decide. Actions only.
+   *
+   * On an error the player stays in `from`. Throws
+   * `SHARD_TRANSFER_REFUSED` when a module refuses,
+   * `SHARD_TRANSFER_NO_PLAYER` when `from` has no entity for the
+   * subscriber, `SHARD_TRANSFER_BUSY` while it is already moving,
+   * `SHARD_TRANSFER_UNSUPPORTED`, or `SHARD_NOT_FOUND`.
+   */
+  transfer(
+    from: string,
+    subscriberId: string,
+    to: string,
+    opts?: { claims?: Record<string, unknown> },
+  ): Promise<ShardTransfer>;
+
+  /**
+   * Send a message to shards on any machine: `"shard:<id>"` for one,
+   * `"group:<name>"` for the shards whose module lists that group, `"all"`
+   * for every shard. The module's `on_message` gets `topic` and `data` as
+   * JSON bytes at the start of its next tick, with an empty sender. For a
+   * GM command, a realm-wide event, or a server-side alert. Actions only.
+   *
+   * Delivery is at most once: a shard that is stopped, busy (1024 messages
+   * waiting), or on a machine that cannot be reached, misses it. Throws
+   * `SHARD_MESSAGE_INVALID` for a bad target, an empty topic (at most 128
+   * bytes), or data over 64 KB.
+   */
+  publish(to: string, topic: string, data?: unknown): Promise<void>;
+
+  /**
+   * Send `input` to shard `shardId`, on any machine. The module's
+   * `apply_input` gets it on the shard's next tick, from the empty
+   * subscriber id (no connection can have it), in the shard's input
+   * format. For a GM command, or a keep claimed on the website.
+   *
+   * In a mutation the input is sent after the mutation commits, and not
+   * at all when it rolls back. Delivery is at most once: a shard that
+   * stops, a full input queue, or a machine that cannot be reached loses
+   * it. In an action, a shard on this machine has it when this resolves.
+   * Throws `SHARD_INPUT_INVALID` for a bad id or an input over 64 KB of
+   * JSON, and in an action `SHARD_NOT_FOUND` or `SHARD_BUSY`.
+   */
+  send(shardId: string, input: unknown): Promise<void>;
+}
+
+/** A finished `ctx.shards.transfer`. */
+export interface ShardTransfer {
+  /** The shard the player is in now. */
+  shard: string;
+  /** A ticket for it, which the transfer frame also carried. */
+  ticket: string;
 }
 
-/** `ctx.shards` in a query or mutation: tickets and reads, no start or stop. */
+/** `ctx.shards` in a query: tickets and reads, no start or stop. */
 export type ShardsReader = Pick<Shards, "ticket" | "get" | "list">;
 
+/** `ctx.shards` in a mutation: a query's, and inputs sent after the commit. */
+export type ShardsWriter = Pick<Shards, "ticket" | "get" | "list" | "send">;
+
 /** A running shard, from `ctx.shards.create`, `get`, or `list`. */
 export interface ShardInfo {
   id: string;
@@ -969,8 +1031,8 @@ export interface MutationCtx<R extends AuthRequirement = "optional"> {
   workflows: Workflows;
   /** Signed file-download URLs — see {@link Files}. */
   files: Files;
-  /** Shard tickets and reads — see {@link Shards}. */
-  shards: ShardsReader;
+  /** Shard tickets, reads, and inputs after the commit — see {@link Shards}. */
+  shards: ShardsWriter;
   /** Create a typed error that triggers rollback. */
   error(code: string, message: string): Error;
   /** Assert org membership (optionally a role) — see {@link RequireMember}. */