dfhack-remote-node 2.0.0

package/dist/index.d.ts

@@ -0,0 +1,228 @@
+/** One RPC method definition. `plugin` is null for core (dfproto) methods. */
+interface MethodDef {
+    plugin: string | null;
+    input: string;
+    output: string;
+}
+declare const METHODS: {
+    readonly BindMethod: {
+        readonly plugin: null;
+        readonly input: "dfproto.CoreBindRequest";
+        readonly output: "dfproto.CoreBindReply";
+    };
+    readonly RunCommand: {
+        readonly plugin: null;
+        readonly input: "dfproto.CoreRunCommandRequest";
+        readonly output: "dfproto.EmptyMessage";
+    };
+    readonly RunLua: {
+        readonly plugin: null;
+        readonly input: "dfproto.CoreRunLuaRequest";
+        readonly output: "dfproto.StringListMessage";
+    };
+    readonly GetVersion: {
+        readonly plugin: null;
+        readonly input: "dfproto.EmptyMessage";
+        readonly output: "dfproto.StringMessage";
+    };
+    readonly GetDFVersion: {
+        readonly plugin: null;
+        readonly input: "dfproto.EmptyMessage";
+        readonly output: "dfproto.StringMessage";
+    };
+    readonly GetWorldInfo: {
+        readonly plugin: null;
+        readonly input: "dfproto.EmptyMessage";
+        readonly output: "dfproto.GetWorldInfoOut";
+    };
+    readonly ListUnits: {
+        readonly plugin: null;
+        readonly input: "dfproto.ListUnitsIn";
+        readonly output: "dfproto.ListUnitsOut";
+    };
+    readonly ListSquads: {
+        readonly plugin: null;
+        readonly input: "dfproto.ListSquadsIn";
+        readonly output: "dfproto.ListSquadsOut";
+    };
+    readonly GetMapInfo: {
+        readonly plugin: "RemoteFortressReader";
+        readonly input: "dfproto.EmptyMessage";
+        readonly output: "RemoteFortressReader.MapInfo";
+    };
+    readonly GetUnitList: {
+        readonly plugin: "RemoteFortressReader";
+        readonly input: "dfproto.EmptyMessage";
+        readonly output: "RemoteFortressReader.UnitList";
+    };
+    readonly GetViewInfo: {
+        readonly plugin: "RemoteFortressReader";
+        readonly input: "dfproto.EmptyMessage";
+        readonly output: "RemoteFortressReader.ViewInfo";
+    };
+    readonly GetWorldMapCenter: {
+        readonly plugin: "RemoteFortressReader";
+        readonly input: "dfproto.EmptyMessage";
+        readonly output: "RemoteFortressReader.WorldMap";
+    };
+};
+/** Names of every method in {@link METHODS}. */
+type MethodName = keyof typeof METHODS;
+
+/** Any decoded reply carries the call's captured console output on `_text`. */
+interface DecodedReply {
+    _text: string;
+    [key: string]: unknown;
+}
+/** A DFHack translated-name sub-message (as decoded by protobufjs). */
+interface NameInfo {
+    englishName?: string;
+    [key: string]: unknown;
+}
+/** Decoded `dfproto.GetWorldInfoOut`. */
+interface GetWorldInfoReply extends DecodedReply {
+    mode?: number;
+    worldName?: NameInfo;
+    saveDir?: string;
+}
+interface DwarfClientOptions {
+    host?: string;
+    port?: number;
+}
+declare class DwarfClient {
+    private readonly root;
+    private readonly conn;
+    private readonly textNotification;
+    private readonly boundIds;
+    constructor({ host, port }?: DwarfClientOptions);
+    private decodeText;
+    /** True once connected and past the handshake. */
+    get connected(): boolean;
+    connect(): Promise<this>;
+    close(): void;
+    /** Resolve (and cache) a method's runtime id via BindMethod. */
+    private bind;
+    /** Call a bound method by name; returns the decoded reply with `_text` attached. */
+    call(name: MethodName, input?: Record<string, unknown>): Promise<DecodedReply>;
+    getVersion(): Promise<string>;
+    getDFVersion(): Promise<string>;
+    getWorldInfo(): Promise<GetWorldInfoReply>;
+    /** Run a DFHack command; returns its console (TEXT) output as a string. */
+    runCommand(command: string, args?: string[]): Promise<string>;
+    /**
+     * Run an arbitrary Lua snippet and return whatever it prints.
+     * The DFHack `lua` command joins its arguments and runs them as a chunk (the
+     * console-only `-e` flag is NOT accepted over RPC — it gets parsed as code),
+     * so the snippet is passed as the argument directly. Console output is captured
+     * via TEXT frames. This is the workhorse for semantic tools: the snippet builds
+     * JSON and prints it.
+     */
+    runLuaSnippet(snippet: string): Promise<string>;
+    /**
+     * Invoke a named Lua function via the core RunLua RPC: `module.function(...args)`.
+     * Returns the function's string-list result. (Distinct from runLuaSnippet: this
+     * calls an existing function, not code.)
+     */
+    callLua(module: string, fn: string, args?: string[]): Promise<string[]>;
+}
+
+/** Turns a TEXT frame body into a string. */
+type TextDecoder = (body: Buffer) => string;
+interface DfConnectionOptions {
+    host?: string;
+    port?: number;
+    textDecoder?: TextDecoder;
+}
+/** Result of one RPC call: the RESULT body plus captured console output. */
+interface CallResult {
+    result: Buffer;
+    text: string;
+}
+declare class DfConnection {
+    readonly host: string;
+    readonly port: number;
+    private readonly decodeText;
+    private sock;
+    private ready;
+    private buf;
+    private shookHands;
+    private queue;
+    private active;
+    private textFrames;
+    constructor({ host, port, textDecoder }?: DfConnectionOptions);
+    /** True once connected and past the handshake. */
+    get connected(): boolean;
+    /** Connect and complete the handshake. Resolves once ready for calls. */
+    connect(): Promise<void>;
+    private onData;
+    private handleFrame;
+    /** Send the next queued call if the socket is idle. */
+    private pump;
+    /**
+     * Send one RPC call. `id` is the bound method id (0 for BindMethod).
+     * Returns { result: Buffer, text: string }.
+     */
+    call(id: number, body: Uint8Array): Promise<CallResult>;
+    private fail;
+    close(): void;
+}
+
+/** Thrown when the peer violates the wire protocol (bad magic, stray frame, …). */
+declare class ProtocolError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when an RPC call returns a FAIL frame.
+ * `code` is DFHack's command_result (see {@link CR}); `text` is any console
+ * (TEXT) output the call produced before failing.
+ */
+declare class RpcError extends Error {
+    readonly code: number;
+    readonly text: string;
+    constructor(message: string, code: number, text?: string);
+}
+
+/** Reserved reply ids (RPCMessageHeader.id) — real methods use non-negative ids. */
+declare const RPC_REPLY: {
+    readonly RESULT: -1;
+    readonly FAIL: -2;
+    readonly TEXT: -3;
+};
+/** Error codes carried in a FAIL frame's size field (DFHack command_result). */
+declare const CR: {
+    readonly LINK_FAILURE: -3;
+    readonly NEEDS_CONSOLE: -2;
+    readonly NOT_IMPLEMENTED: -1;
+    readonly OK: 0;
+    readonly FAILURE: 1;
+    readonly WRONG_USAGE: 2;
+    readonly NOT_FOUND: 3;
+};
+/** One parsed reply frame. `body` is null for FAIL frames (size holds the errno). */
+interface Frame {
+    id: number;
+    size: number;
+    body: Buffer | null;
+}
+/** A frame plus how many bytes it consumed from the front of the buffer. */
+interface ParsedFrame {
+    frame: Frame;
+    consumed: number;
+}
+/** Encode one request message: 8-byte header (id, pad, size) + body. */
+declare function encodeMessage(id: number, body: Uint8Array): Buffer;
+/**
+ * Try to read the handshake reply from the front of `buf`.
+ * Returns the number of bytes consumed (HANDSHAKE_LEN) once available, or 0 if
+ * more data is needed. Throws ProtocolError if the magic doesn't match.
+ */
+declare function readHandshake(buf: Buffer): number;
+/**
+ * Try to parse one frame off the front of `buf`.
+ * Returns { frame, consumed }, or null if a complete frame isn't available yet.
+ * For FAIL frames `size` is the errno and `body` is null; for RESULT/TEXT `body`
+ * is a Buffer of length `size`.
+ */
+declare function readFrame(buf: Buffer): ParsedFrame | null;
+
+export { CR, type CallResult, type DecodedReply, DfConnection, type DfConnectionOptions, DwarfClient, type DwarfClientOptions, type Frame, type GetWorldInfoReply, METHODS, type MethodDef, type MethodName, type NameInfo, type ParsedFrame, ProtocolError, RPC_REPLY, RpcError, type TextDecoder, encodeMessage, readFrame, readHandshake };