@tsln/console 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,63 @@
+# @tsln/console
+
+The Max console as a [Console API](https://developer.mozilla.org/docs/Web/API/console) object
+for `[v8]` scripts: `log`, `info`, `warn`, `error`, `assert`, `trace`, `dir`, `table`, `group`,
+`count`, `time` and the rest. Values are formatted by `inspect()`, which handles circular
+references, functions, Map and Set, errors, and summarises Max and Live objects (`Maxobj`, `Dict`,
+`LiveAPI`, `LiveObject`) instead of expanding their internals. A leading string can hold format
+specifiers (`%s`, `%d`, `%i`, `%f`, `%o`, `%O`, `%j`, `%c`, `%%`).
+
+```ts
+import console = require("./vendor/console");
+
+console.log("tracks:", song.tracks); // tracks: [LiveObject<Track> live_set tracks 0, ...]
+console.log("%d of %d", done, total);
+console.error("no input on", index); // in red
+console.warn("careful"); // "warning: careful", since the Max console has no warning level
+console.group("connecting");
+console.log("indented");
+console.groupEnd();
+console.time("render");
+console.timeEnd("render"); // render: 12 ms
+console.dir(deep, { depth: 6 }); // more than log() shows
+```
+
+The module is also callable, as a shorthand for `log()`, so `import log = require("./vendor/console")`
+and `log("loaded")` work too.
+
+## As the global `console`
+
+A bundled npm package looks for `console` as a global. `install()` provides it, keeping a console
+Max supplies itself and adding only the methods it lacks:
+
+```ts
+console.install();
+import thing = require("./vendor/thing");
+```
+
+## Log file
+
+`logToFile(path)` also writes every line to a file, timestamped and with its level; `logToFile(null)`
+stops. Use an absolute path.
+
+## Install
+
+```sh
+npm install --save-dev @tsln/console
+```
+
+Max's `require()` searches Max's file path and knows nothing of `node_modules`, so the package's
+single CommonJS file, `dist/index.js`, has to be copied or bundled to somewhere Max can find it
+(the `max-msp` repository bundles it to `js/vendor/console.js` with esbuild), with a declaration
+file next to it for the types:
+
+```ts
+// src/vendor/console.d.ts
+import console = require("@tsln/console");
+export = console;
+```
+
+The package depends on `@tsln/max-types` for the Max globals it calls (`post`, `error`, `File`).
+
+Where the Console API has no Max equivalent: `table` posts the data like `log`, and `clear` does
+nothing, since a script can't clear the Max console.

package/dist/index.d.ts

@@ -0,0 +1,110 @@
+/// <reference types="@tsln/max-types" preserve="true" />
+interface InspectOptions {
+    /** How many levels of nested objects and arrays to expand. Default 3. */
+    depth?: number;
+    /** How many array items or object keys to show before summarizing the rest. Default 50. */
+    maxItems?: number;
+}
+/**
+ * Formats any value as readable text for debugging. Unlike JSON.stringify it handles
+ * circular references (`[Circular]`), functions, undefined, Map/Set, errors, and
+ * summarizes Max and Live objects instead of expanding their internals.
+ *
+ * @example
+ * inspect({ a: 1, list: [1, 2] }); // { a: 1, list: [1, 2] }
+ */
+declare function inspect(value: unknown, options?: InspectOptions): string;
+/**
+ * Also writes everything posted through this module to a file, one timestamped line per
+ * call. Lines are appended, and the file is created if it doesn't exist. Pass null to stop.
+ *
+ * Use an absolute path; how Max resolves relative paths for writing isn't documented.
+ * If the file can't be opened, an error is posted and file logging stops.
+ *
+ * @param path the file to write to, e.g. "C:/Users/me/Documents/spat.log"
+ * @example
+ * console.logToFile("C:/Users/me/Documents/spat.log");
+ * console.log("connecting", tracks); // console, and "2026-09-14T10:15:00.000Z [log] connecting [...]" in the file
+ */
+declare function logToFile(path: string | null): void;
+/**
+ * Posts values to the Max console, formatted with inspect(). Strings are posted as they are,
+ * and a leading string can hold format specifiers (`%s`, `%d`, `%o`, ...).
+ *
+ * @example
+ * console.log("tracks:", song.tracks); // tracks: [LiveObject<Track> live_set tracks 0, ...]
+ * console.log("%d of %d", done, total);
+ */
+declare function log(...values: unknown[]): void;
+/** Same as log(); the Console API has both. */
+declare function info(...values: unknown[]): void;
+/** Same as log(); the Console API has both. */
+declare function debug(...values: unknown[]): void;
+/** Posts values like log(), prefixed with "warning:", as the Max console has no warning level. */
+declare function warn(...values: unknown[]): void;
+/**
+ * Posts values to the Max console as an error (in red), formatted like log().
+ *
+ * @example
+ * console.error("no audio input", index);
+ */
+declare function logError(...values: unknown[]): void;
+/** Posts values as an error when the condition is false; nothing otherwise. */
+declare function assert(condition: unknown, ...values: unknown[]): void;
+/** Posts values as an error, followed by the stack of the call. */
+declare function trace(...values: unknown[]): void;
+/**
+ * Posts one value expanded with inspect(), with its options: `console.dir(x, { depth: 6 })`
+ * shows more of a deep object than log() would.
+ */
+declare function dir(value: unknown, options?: InspectOptions): void;
+/** Posts the data like log(); the Max console has no tables. */
+declare function table(data: unknown): void;
+/** Starts an indented group of output, headed by the label if there is one. */
+declare function group(...label: unknown[]): void;
+/** Ends the innermost group. */
+declare function groupEnd(): void;
+/** Posts how many times count() has been called with the label. */
+declare function count(label?: unknown): void;
+/** Resets the counter for the label. */
+declare function countReset(label?: unknown): void;
+/** Starts a timer under the label. Max reports in milliseconds, as a browser does. */
+declare function time(label?: unknown): void;
+/** Posts the time since time(label), keeping the timer running. */
+declare function timeLog(label?: unknown, ...values: unknown[]): void;
+/** Posts the time since time(label) and stops the timer. */
+declare function timeEnd(label?: unknown): void;
+/** Does nothing: a script can't clear the Max console. Here so callers don't have to check. */
+declare function clear(): void;
+/**
+ * Makes this the global `console`, for bundled npm packages and other code that expects
+ * one. A console Max provides itself is kept, and only the methods it lacks are added, so
+ * this is safe to call whether or not Max has grown one.
+ */
+declare function install(): void;
+declare const _default: typeof log & {
+    log: typeof log;
+    info: typeof info;
+    debug: typeof debug;
+    warn: typeof warn;
+    error: typeof logError;
+    assert: typeof assert;
+    trace: typeof trace;
+    dir: typeof dir;
+    dirxml: typeof log;
+    table: typeof table;
+    group: typeof group;
+    groupCollapsed: typeof group;
+    groupEnd: typeof groupEnd;
+    count: typeof count;
+    countReset: typeof countReset;
+    time: typeof time;
+    timeLog: typeof timeLog;
+    timeEnd: typeof timeEnd;
+    clear: typeof clear;
+} & {
+    logToFile: typeof logToFile;
+    inspect: typeof inspect;
+    install: typeof install;
+};
+export = _default;

package/dist/index.js

@@ -0,0 +1,282 @@
+"use strict";
+
+// src/index.ts
+function inspect(value, options = {}) {
+  const depth = options.depth ?? 3;
+  const maxItems = options.maxItems ?? 50;
+  const ancestors = /* @__PURE__ */ new Set();
+  function format(value2, level, quoteStrings) {
+    switch (typeof value2) {
+      case "string":
+        return quoteStrings ? JSON.stringify(value2) : value2;
+      case "number":
+      case "boolean":
+      case "undefined":
+        return String(value2);
+      case "bigint":
+        return `${value2}n`;
+      case "symbol":
+        return value2.toString();
+      case "function":
+        return `[Function ${value2.name || "anonymous"}]`;
+    }
+    if (value2 === null) return "null";
+    const object = value2;
+    if (ancestors.has(object)) return "[Circular]";
+    try {
+      const summary = summarize(object);
+      if (summary !== void 0) return summary;
+      const name = object.constructor?.name;
+      const isPlain = !name || name === "Object";
+      if (level >= depth) {
+        return Array.isArray(object) ? `[Array(${object.length})]` : `[${name || "Object"}]`;
+      }
+      ancestors.add(object);
+      try {
+        if (Array.isArray(object)) {
+          return `[${joinItems(object, (item) => format(item, level + 1, true))}]`;
+        }
+        if (object instanceof Map) {
+          const entries2 = joinItems(
+            [...object],
+            ([k, v]) => `${format(k, level + 1, true)} => ${format(v, level + 1, true)}`
+          );
+          return `Map(${object.size}) ${braces(entries2)}`;
+        }
+        if (object instanceof Set) {
+          return `Set(${object.size}) ${braces(joinItems([...object], (item) => format(item, level + 1, true)))}`;
+        }
+        const entries = joinItems(
+          Object.keys(object),
+          (key) => `${key}: ${format(object[key], level + 1, true)}`
+        );
+        return `${isPlain ? "" : `${name} `}${braces(entries)}`;
+      } finally {
+        ancestors.delete(object);
+      }
+    } catch (e) {
+      return `[unprintable: ${e}]`;
+    }
+  }
+  function joinItems(items, formatItem) {
+    const parts = items.slice(0, maxItems).map(formatItem);
+    if (items.length > maxItems) parts.push(`... ${items.length - maxItems} more`);
+    return parts.join(", ");
+  }
+  function braces(contents) {
+    return contents ? `{ ${contents} }` : "{}";
+  }
+  function summarize(object) {
+    if (object instanceof Error) {
+      return `${object.name}: ${object.message}`;
+    }
+    if (object instanceof Date) {
+      return object.toISOString();
+    }
+    if (typeof LiveAPI !== "undefined" && object.api instanceof LiveAPI) {
+      return Number(object.api.id) === 0 ? "LiveObject (no object)" : `LiveObject<${object.api.type}> ${object.api.unquotedpath}`;
+    }
+    if (typeof LiveAPI !== "undefined" && object instanceof LiveAPI) {
+      return `LiveAPI<${object.type}> ${object.unquotedpath}`;
+    }
+    if (typeof Dict !== "undefined" && object instanceof Dict) {
+      return `Dict "${object.name}" ${object.stringify_compressed()}`;
+    }
+    if (typeof object.maxclass === "string" && typeof object.getattr === "function") {
+      return `Maxobj<${object.maxclass}>${object.varname ? ` "${object.varname}"` : ""}`;
+    }
+    return void 0;
+  }
+  return format(value, 0, false);
+}
+function formatValues(values) {
+  const rest = [...values];
+  const parts = [];
+  if (typeof rest[0] === "string" && rest[0].includes("%")) {
+    const template = rest.shift();
+    parts.push(
+      template.replace(/%([sdifoOjc%])/g, (match, spec) => {
+        if (spec === "%") return "%";
+        if (spec === "c") {
+          rest.shift();
+          return "";
+        }
+        if (rest.length === 0) return match;
+        const value = rest.shift();
+        switch (spec) {
+          case "s":
+            return typeof value === "string" ? value : inspect(value, { depth: 1 });
+          case "d":
+          case "i":
+            return typeof value === "bigint" ? `${value}n` : String(Math.trunc(Number(value)));
+          case "f":
+            return String(Number(value));
+          case "j":
+            try {
+              return JSON.stringify(value);
+            } catch {
+              return "[Circular]";
+            }
+          default:
+            return inspect(value, { depth: 4 });
+        }
+      })
+    );
+  }
+  for (const value of rest) {
+    parts.push(inspect(value));
+  }
+  return parts.join(" ");
+}
+function maxError(...args) {
+  const fn = globalThis.error ?? error;
+  fn(...args);
+}
+var logFilePath = null;
+function logToFile(path) {
+  logFilePath = path;
+}
+function appendToLogFile(level, text) {
+  if (!logFilePath) {
+    return;
+  }
+  let file = new File(logFilePath, "readwrite");
+  if (!file.isopen) {
+    file = new File(logFilePath, "write");
+  }
+  if (!file.isopen) {
+    const path = logFilePath;
+    logFilePath = null;
+    maxError(`log file: couldn't open ${path}; file logging stopped`, "\n");
+    return;
+  }
+  try {
+    file.position = file.eof;
+    file.writeline(`${(/* @__PURE__ */ new Date()).toISOString()} [${level}] ${text}`);
+  } finally {
+    file.close();
+  }
+}
+var groupDepth = 0;
+function write(level, values) {
+  const text = formatValues(values);
+  const line = "  ".repeat(groupDepth) + (level === "warn" ? `warning: ${text}` : text);
+  if (level === "error") {
+    maxError(line, "\n");
+  } else {
+    post(line, "\n");
+  }
+  appendToLogFile(level, text);
+}
+function log(...values) {
+  write("log", values);
+}
+function info(...values) {
+  write("info", values);
+}
+function debug(...values) {
+  write("debug", values);
+}
+function warn(...values) {
+  write("warn", values);
+}
+function logError(...values) {
+  write("error", values);
+}
+function assert(condition, ...values) {
+  if (condition) return;
+  write("error", values.length ? ["Assertion failed:", ...values] : ["Assertion failed"]);
+}
+function trace(...values) {
+  const stack = (new Error().stack ?? "").split("\n").slice(2).map((line) => line.trim()).filter(Boolean);
+  const text = values.length ? formatValues(values) : "Trace";
+  write("error", [stack.length ? `${text}
+    ${stack.join("\n    ")}` : text]);
+}
+function dir(value, options) {
+  write("log", [inspect(value, options)]);
+}
+function table(data) {
+  write("log", [data]);
+}
+function group(...label) {
+  if (label.length) write("log", label);
+  groupDepth++;
+}
+function groupEnd() {
+  groupDepth = Math.max(0, groupDepth - 1);
+}
+var counts = /* @__PURE__ */ new Map();
+var timers = /* @__PURE__ */ new Map();
+function count(label = "default") {
+  const key = String(label);
+  const n = (counts.get(key) ?? 0) + 1;
+  counts.set(key, n);
+  write("log", [`${key}: ${n}`]);
+}
+function countReset(label = "default") {
+  counts.delete(String(label));
+}
+function time(label = "default") {
+  const key = String(label);
+  if (timers.has(key)) {
+    warn(`Timer '${key}' already exists`);
+    return;
+  }
+  timers.set(key, Date.now());
+}
+function elapsed(label) {
+  const key = String(label);
+  const start = timers.get(key);
+  if (start === void 0) {
+    warn(`Timer '${key}' does not exist`);
+    return void 0;
+  }
+  return [key, `${key}: ${Date.now() - start} ms`];
+}
+function timeLog(label = "default", ...values) {
+  const result = elapsed(label);
+  if (result) write("log", [result[1], ...values]);
+}
+function timeEnd(label = "default") {
+  const result = elapsed(label);
+  if (!result) return;
+  timers.delete(result[0]);
+  write("log", [result[1]]);
+}
+function clear() {
+}
+var methods = {
+  log,
+  info,
+  debug,
+  warn,
+  error: logError,
+  assert,
+  trace,
+  dir,
+  dirxml: log,
+  table,
+  group,
+  groupCollapsed: group,
+  groupEnd,
+  count,
+  countReset,
+  time,
+  timeLog,
+  timeEnd,
+  clear
+};
+function install() {
+  const target = globalThis;
+  if (!target.console) {
+    target.console = { ...methods };
+    return;
+  }
+  for (const [name, fn] of Object.entries(methods)) {
+    if (typeof target.console[name] !== "function") {
+      target.console[name] = fn;
+    }
+  }
+}
+module.exports = Object.assign(log, methods, { logToFile, inspect, install });

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@tsln/console",
+  "version": "0.0.0",
+  "description": "The Max console as a Console API object for [v8] scripts, with an install() that makes it the global console for bundled packages",
+  "license": "MIT",
+  "author": "Mateo Murphy",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tsln-lab/max-packages.git",
+    "directory": "packages/console"
+  },
+  "keywords": [
+    "max",
+    "msp",
+    "max-msp",
+    "max-for-live",
+    "v8",
+    "console",
+    "logging",
+    "typescript"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@tsln/max-types": "^0.1.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.2",
+    "typescript": "7.0.2"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && esbuild src/index.ts --bundle --format=cjs --platform=neutral --target=es2022 --outfile=dist/index.js --log-level=warning",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node tests/console.test.cjs"
+  }
+}