@tsln/max-api-types 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mateo Murphy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# @tsln/max-api-types
+
+Type declarations for `max-api`, the module Max's `[node.script]` object provides to the
+Node.js process it runs (Node for Max), transcribed from the
+[reference](https://docs.cycling74.com/apiref/nodeformax/).
+
+This is the Node.js side of Max. For scripts in `[v8]`, `[js]` and their UI variants see
+[`@tsln/max-types`](../max-types); the two declare globals of the same names and can't be
+loaded together. A project with both kinds of script gives each its own folder and
+`tsconfig.json`; the [repository README](../../README.md#using-the-v8-and-nodescript-types-in-one-project)
+shows the layout.
+
+## Install
+
+```sh
+npm install --save-dev @tsln/max-api-types @types/node
+```
+
+`max-api` isn't a package to install: `[node.script]` injects it. The declarations are ambient,
+so list the package in `types` and require the module as usual:
+
+```jsonc
+{
+  "compilerOptions": {
+    "types": ["node", "@tsln/max-api-types"]
+  }
+}
+```
+
+```ts
+import maxAPI = require("max-api");
+
+maxAPI.addHandlers({
+  bang: () => maxAPI.outletBang(),
+  number: (value) => maxAPI.outlet(value * 2), // value: number
+  list: (...values) => maxAPI.outlet(values.length), // values: (string | number)[]
+  dict: (dict) => maxAPI.post(dict.gain), // dict: JSONObject
+  gain: (db: number) => { ... }, // a message of the script's own: `gain -6`
+  [maxAPI.MESSAGE_TYPES.ALL]: (handled, ...args) => {
+    if (!handled) maxAPI.post("unhandled:", args, maxAPI.POST_LEVELS.WARN);
+  },
+});
+```
+
+## Compared to `@types/max-api`
+
+DefinitelyTyped has typings for the same module. These differ in two ways:
+
+- The module is declared with `export =`, so `import maxAPI = require("max-api")` gives the API
+  directly, as it does at runtime, instead of an object with a `default` property.
+- Handlers for the predefined selectors (`bang`, `number`, `list`, `dict`, `all`) are typed with
+  what they receive, through `addHandler` and `addHandlers` alike. Handlers for messages of the
+  script's own stay open, as `(...args: any[]) => void`.
+
+`MAX_ENV`, `MESSAGE_TYPES` and `POST_LEVELS` are declared as the objects of strings they are at
+runtime rather than as enums, so the plain strings work wherever the constants do.
+`process.env.MAX_ENV` is typed with the `MAX_ENV` values.

package/index.d.ts

@@ -0,0 +1,160 @@
+// Type declarations for the "max-api" module that Max's [node.script] object provides to the
+// Node.js process it runs. Transcribed from https://docs.cycling74.com/apiref/nodeformax/
+//
+// This is a Node.js API, not the [v8]/[js] one: it goes with @types/node, and must not be
+// loaded together with @tsln/max-types, which declares globals of the same names.
+
+declare module "max-api" {
+  // ---- values ----
+
+  /** A single Max atom, as they arrive in a list or a message. */
+  type Atom = string | number;
+
+  type JSONPrimitive = string | number | boolean | null;
+  type JSONArray = JSONValue[];
+  interface JSONObject {
+    [key: string]: JSONValue | undefined;
+  }
+  type JSONValue = JSONPrimitive | JSONArray | JSONObject;
+
+  /** What post() accepts: atoms, a list of atoms, or something JSON-like. */
+  type Anything = string | number | Atom[] | JSONObject | JSONArray;
+
+  // ---- constants ----
+  //
+  // The reference presents these as enums; at runtime they are plain objects of strings,
+  // which is how they are declared here so that the strings themselves can be used too.
+
+  /** Values Node for Max sets `process.env.MAX_ENV` to. */
+  const MAX_ENV: {
+    /** node.script running from within Max */
+    readonly MAX: "max";
+    /** node.script running from within Max for Live */
+    readonly MAX_FOR_LIVE: "maxforlive";
+    /** node.script running from within a standalone application */
+    readonly STANDALONE: "max:standalone";
+  };
+  type MaxEnv = (typeof MAX_ENV)[keyof typeof MAX_ENV];
+
+  /** The predefined selectors a handler can be registered for. */
+  const MESSAGE_TYPES: {
+    /** Every message, after the more specific handlers */
+    readonly ALL: "all";
+    /** A bang */
+    readonly BANG: "bang";
+    /** A dictionary */
+    readonly DICT: "dict";
+    /** A list (a message starting with a number) */
+    readonly LIST: "list";
+    /** A single number */
+    readonly NUMBER: "number";
+  };
+  type MessageType = (typeof MESSAGE_TYPES)[keyof typeof MESSAGE_TYPES];
+
+  /** Log levels for post(), given as its last argument. */
+  const POST_LEVELS: {
+    readonly ERROR: "error";
+    readonly INFO: "info";
+    readonly WARN: "warn";
+  };
+  type PostLevel = (typeof POST_LEVELS)[keyof typeof POST_LEVELS];
+
+  // ---- handlers ----
+
+  /** What a handler receives for each predefined selector. */
+  interface MessageHandlers {
+    /**
+     * Called for every message, after any more specific handler. `handled` says whether
+     * another handler already took the message; the rest is the message as received.
+     */
+    all: (handled: boolean, ...args: any[]) => void;
+    bang: () => void;
+    /** The dictionary's contents. */
+    dict: (dict: JSONObject) => void;
+    /** The elements of the list. */
+    list: (...values: Atom[]) => void;
+    number: (value: number) => void;
+  }
+
+  /** A handler for a message of the script's own, `selector arg1 arg2 ...`. */
+  type AnyHandler = (...args: any[]) => void;
+
+  /** Either a predefined selector or a message name of the script's own. */
+  type MaxFunctionSelector = MessageType | (string & {});
+
+  /** The handler type for a selector: typed for the predefined ones, open for the rest. */
+  type MaxFunctionHandler<S extends string = string> = S extends keyof MessageHandlers
+    ? MessageHandlers[S]
+    : AnyHandler;
+
+  /** Handlers by selector, as addHandlers() takes them. */
+  interface HandlerMap extends Partial<MessageHandlers> {
+    [selector: string]: AnyHandler | undefined;
+  }
+
+  /**
+   * Registers a handler for a selector: a predefined MESSAGE_TYPES value, or the first
+   * word of a message of the script's own.
+   * @example
+   * maxAPI.addHandler("list", (...values) => maxAPI.outlet(values.length));
+   * maxAPI.addHandler("gain", (db: number) => { ... });
+   */
+  function addHandler<S extends string>(selector: S, handler: MaxFunctionHandler<S>): void;
+
+  /**
+   * Registers several handlers at once, keyed by selector.
+   * @example
+   * maxAPI.addHandlers({
+   *   bang: () => maxAPI.outletBang(),
+   *   [maxAPI.MESSAGE_TYPES.ALL]: (handled, ...args) => { if (!handled) maxAPI.post(args); },
+   * });
+   */
+  function addHandlers(handlers: HandlerMap): void;
+
+  /** Removes one handler previously registered for the selector. */
+  function removeHandler<S extends string>(selector: S, handler: MaxFunctionHandler<S>): void;
+
+  /** Removes every handler registered for the selector. */
+  function removeHandlers(selector: MaxFunctionSelector): void;
+
+  // ---- output ----
+
+  /**
+   * Sends the values out of the [node.script] outlet: atoms as a message or list, arrays
+   * and objects as a dictionary. Resolves once Max has received them.
+   */
+  function outlet(...args: JSONValue[]): Promise<void>;
+
+  /** Sends a bang out of the [node.script] outlet. */
+  function outletBang(): Promise<void>;
+
+  /**
+   * Posts to the Max console. A POST_LEVELS value as the last argument sets the level.
+   * @example
+   * maxAPI.post("something went wrong", maxAPI.POST_LEVELS.ERROR);
+   */
+  function post(...args: (Anything | PostLevel)[]): Promise<void>;
+
+  // ---- dictionaries ----
+
+  /** Reads the contents of the named [dict]. */
+  function getDict(id: string): Promise<JSONObject>;
+
+  /** Replaces the contents of the named [dict], and resolves with the new contents. */
+  function setDict(id: string, dict: JSONObject): Promise<JSONObject>;
+
+  /**
+   * Sets one value in the named [dict] at a path such as `"a.b.c"` or `"items[2]"`, and
+   * resolves with the whole new contents.
+   */
+  function updateDict(id: string, updatePath: string, updateValue: JSONValue): Promise<JSONObject>;
+
+  global {
+    namespace NodeJS {
+      interface ProcessEnv {
+        /** Set by Node for Max to say what the script is running inside; see MAX_ENV. */
+        MAX_ENV?: MaxEnv;
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@tsln/max-api-types",
+  "version": "0.0.0",
+  "description": "Type declarations for the max-api module of Max's [node.script] object (Node for Max)",
+  "license": "MIT",
+  "author": "Mateo Murphy",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tsln-lab/max-packages.git",
+    "directory": "packages/max-api-types"
+  },
+  "keywords": [
+    "max",
+    "msp",
+    "max-msp",
+    "node-for-max",
+    "node.script",
+    "max-api",
+    "cycling74",
+    "typescript",
+    "types"
+  ],
+  "types": "./index.d.ts",
+  "files": [
+    "*.d.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "7.0.2"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json"
+  }
+}