[auto-generated][maxmsp] Correct several signatures verified against Max for Live 8 by nemtsov · Pull Request #74975 · DefinitelyTyped/DefinitelyTyped

nemtsov · 2026-05-10T13:54:49Z

This PR corrects several declarations in types/maxmsp/index.d.ts that were
verified against actual Max for Live 8 runtime behavior, public M4L source
code on GitHub, and the C74 apiref pages.

Note: this PR was prepared with assistance from a coding agent (Claude Code) acting on a brief I wrote based on bugs I hit while writing M4L JavaScript that consumes @types/maxmsp. Each item below has runtime evidence I gathered myself in Max for Live 8, plus corroborating public sources. I'm including [auto-generated] in the title per repo policy.

Changes

Max.appath → Max.apppath — typo. 13+ real-world usages on GitHub
(gh search code 'max.apppath' --language=javascript); zero usages of
max.appath. C74 apiref also lists apppath
(https://docs.cycling74.com/apiref/js/max/).
SQLite.begintransaction() → SQLite.starttransaction() — verified at
runtime: typeof db.starttransaction === "function",
typeof db.begintransaction === "undefined". The C74 apiref names it
starttransaction (https://docs.cycling74.com/apiref/js/sqlite/).
Removed Folder.append() — the JSDoc was a duplicate of reset()'s
description and no Max code uses it. C74 apiref lists no such method
(https://docs.cycling74.com/apiref/js/folder/). Also replaced the stale
"Documentation is faulty, this has been reported." comment on
Folder.reset() with a real description.
Sketch.glbegin(draw_prim: any[]) → glbegin(draw_prim: string) —
real usages pass strings ('quad_strip', "lines"); the same class's
shapeprim(draw_prim: string) JSDoc enumerates the valid string primitives.
LiveAPI.id: number → LiveAPI.id: string — runtime check:
typeof api.id === "string" (returns e.g. "1"). The legacy vignette
correctly described it as "Dynamic string identifier"
(https://docs.cycling74.com/legacy/max8/vignettes/jsliveapi).
Added LiveAPI.valid: number (readonly) — documented in the apiref
and present at runtime, but missing from the declaration. JSDoc notes
that the property's reported value has been observed as 0 even when
id is non-zero, so it is not a reliable guard in all Live versions.
Added five MGraphics methods previously missing — paint(),
paint_with_alpha(), clear_surface(), new_path(),
image_surface_draw_fast(). All are referenced either in widespread
public M4L code or in the Cycling '74 SDK's own jsurface HTML doc.
Task constructor JSDoc: clarified that the third+ arguments are
spread as separate arguments[i] entries, not collected into a single
array. Verified at runtime: new Task(fn, this, ["a","b","c"]) results
in arguments.length === 1, with arguments[0] being the array.

Test file

maxmsp-tests.ts updated to match: testmax.apppath,
mySQLite.starttransaction(), sketchInstance.glbegin("lines"). No new
public symbols required new test cases beyond the renames.

Verification

dtslint types/maxmsp/ runs clean (exit 0).

cc @twhiston @FrancescElies (current owners per package.json).

Fixes verified against Max for Live 8 runtime, real-world public M4L JS code, and the Cycling '74 apiref: - Max.appath -> Max.apppath (typo; 13+ real usages of `apppath`, zero of `appath`). - SQLite.begintransaction() -> SQLite.starttransaction() (runtime check: `typeof db.starttransaction === "function"`, begintransaction is undefined). - Removed Folder.append() (no such method; JSDoc was a duplicate of reset()'s). Also replaced the stale "Documentation is faulty" JSDoc on Folder.reset(). - Sketch.glbegin(draw_prim: any[]) -> glbegin(draw_prim: string). Real usages pass strings ('quad_strip', 'lines'); same class's shapeprim() already takes a string with the same valid set. - LiveAPI.id: number -> LiveAPI.id: string. Runtime check: `typeof api.id === "string"` (returns e.g. "1"). Legacy vignette agrees ("Dynamic string identifier"). - Added LiveAPI.valid: number (readonly). Documented in apiref, present at runtime, missing from the declaration. - Added MGraphics methods missing from the file but present at runtime and in widespread use: paint(), paint_with_alpha(), clear_surface(), new_path(), image_surface_draw_fast(). - Task constructor JSDoc: clarified that the third+ args are spread as separate arguments, not collected into one array (verified at runtime). Updated maxmsp-tests.ts to match: testmax.apppath, mySQLite.starttransaction(), sketchInstance.glbegin("lines").

typescript-bot · 2026-05-10T13:55:23Z

@nemtsov Thank you for submitting this PR! I see this is your first time submitting to DefinitelyTyped 👋 — I'm the local bot who will help you through the process of getting things through.

This is a live comment that I will keep updated.

1 package in this PR

maxmsp — on npm, on unpkg

Code Reviews

Because you edited one package and updated the tests (👏), I can help you merge this PR once someone else signs off on it.

You can test the changes of this PR in the Playground.

Status

✅ No merge conflicts
✅ Continuous integration tests have passed
🕐 Most recent commit is approved by type definition owners, DT maintainers or others

Once every item on this list is checked, I'll ask you for permission to merge and publish the changes.

Diagnostic Information: What the bot saw about this PR

{
  "type": "info",
  "now": "-",
  "pr_number": 74975,
  "author": "nemtsov",
  "headCommitOid": "1eeb3b5388ab73afdedb52017963143d698067fe",
  "mergeBaseOid": "dafc26dc3da728f912025f73d2629374a9b1aba9",
  "lastPushDate": "2026-05-10T13:54:49.000Z",
  "lastActivityDate": "2026-05-10T15:10:20.000Z",
  "hasMergeConflict": false,
  "isFirstContribution": true,
  "tooManyFiles": false,
  "hugeChange": false,
  "tooManyCommits": false,
  "tooManyReviews": false,
  "popularityLevel": "Well-liked by everyone",
  "pkgInfo": [
    {
      "name": "maxmsp",
      "kind": "edit",
      "files": [
        {
          "path": "types/maxmsp/index.d.ts",
          "kind": "definition"
        },
        {
          "path": "types/maxmsp/maxmsp-tests.ts",
          "kind": "test"
        }
      ],
      "owners": [
        "twhiston",
        "FrancescElies"
      ],
      "addedOwners": [],
      "deletedOwners": [],
      "popularityLevel": "Well-liked by everyone"
    }
  ],
  "reviews": [],
  "mainBotCommentID": 4415458707,
  "ciResult": "pass"
}

typescript-bot · 2026-05-10T13:55:24Z

🔔 @twhiston @FrancescElies — please review this PR in the next few days. Be sure to explicitly select Approve or Request Changes in the GitHub UI so I know what's going on.

nemtsov · 2026-05-10T14:15:49Z

This PR creation was a bit premature. I'll reopen it when it's ready and I've manually tested all of the changes. Apologies for the notifications.

twhiston · 2026-05-10T14:56:31Z

No worries. I know these types generally need some updates for max 9 as well. Whenever these are ready I’ll be sure to give them a look.
The testing for definitely typed are not the best for max so I’d really appreciate it if you validated all your changes by testing all the functions in max itself where possible, especially if you are using a coding agent as they seem particularly bad when it comes to getting the max api correct

nemtsov · 2026-05-10T14:57:44Z

Thanks @twhiston ! I now ran the manual tests for everything in [js] and [jsui] in M4L.

Update — runtime verification

I verified each assertion in this PR against Max for Live 8 (8.5.8) using a small test script (bang-triggered, prints to the Max console). Results:

#	Change	Runtime result
1	`Max.appath` → `Max.apppath`	PASS — `typeof max.apppath === "string"` (returned the real Max app path); `typeof max.appath === "undefined"`
2	`SQLite.begintransaction()` → `starttransaction()`	PASS — `typeof db.starttransaction === "function"`; `typeof db.begintransaction === "undefined"`; `endtransaction` still a function
3	Removed `Folder.append()`	PASS — `typeof f.append === "undefined"`; `reset`/`next`/`close` all functions
4	`Sketch.glbegin(any[])` → `glbegin(string)`	No runtime contradiction — Max accepts both `"lines"` and `["lines"]` silently in `[jsui]` (gl methods rarely throw on bad input). Justification rests on: C74 apiref documents a string parameter, the sibling `Sketch.shapeprim()` is already typed `string` with the same valid value list, and 100% of public Max code on GitHub passes a string. The original `any[]` matches no real caller.
5	`LiveAPI.id: number` → `string`	PASS — `typeof api.id === "string"` (e.g. `"1"`)
6	Added `LiveAPI.valid: number` (readonly)	PASS — `typeof api.valid === "number"`. Notably `api.valid` reported `5e-324` (≈ 0) on a `LiveAPI("live_set")` whose `id` was non-zero — directly confirming the "may report 0 even when id is non-zero" caveat in the JSDoc.
7	Added `paint`, `paint_with_alpha`, `clear_surface`, `new_path`, `image_surface_draw_fast` on `MGraphics`	PASS — all five present on a real `new MGraphics(64, 64)` instance inside `[jsui]` (`typeof mg[name] === "function"` for each)
8	`Task` constructor JSDoc clarified (varargs, not array)	PASS — `new Task(fn, this, "a", "b", "c")` → callback's `arguments.length === 3`; `new Task(fn, this, ["a", "b", "c"])` → `arguments.length === 1` with `arguments[0]` being the array
9	`Folder.reset` JSDoc cleanup	Documentation-only; reuses the (correct) text that was on the deleted `Folder.append`. Confirmed against current C74 apiref.

Notes on environment: probes ran in M4L 8.5.8 on macOS. The [js] and [jsui] contexts have different constraints — Sketch and MGraphics cannot be safely instantiated in [js] (the former triggers infinite recursion in sketch_enforcecontext), so Bugs 4 and 7 were verified inside [jsui]. All others ran in [js].

Happy to share the verification scripts if useful.

twhiston · 2026-05-10T15:02:05Z

I would suggest testing against the v8 object since js is effectively deprecated in modern max and these types will be targeting v8 from now on (you’d still be able to use an old version with the js object but since I don’t expect that cycling will make any future changes to it, but are actively improving v8, and most people are porting their stuff over to v8, it makes more sense for these to target that from now on)

nemtsov · 2026-05-10T15:10:20Z

I'm, unfortunately, still on Live 11 with Max 8 (and without a [v8]). Would it make sense to have a maxmsp/v8/ and maxmsp/v9/?

typescript-bot added this to Pull Request Status Board May 10, 2026

typescript-bot moved this to Waiting for Code Reviews in Pull Request Status Board May 10, 2026

nemtsov closed this May 10, 2026

typescript-bot removed this from Pull Request Status Board May 10, 2026

nemtsov reopened this May 10, 2026

typescript-bot added this to Pull Request Status Board May 10, 2026

typescript-bot moved this to Waiting for Code Reviews in Pull Request Status Board May 10, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[auto-generated][maxmsp] Correct several signatures verified against Max for Live 8#74975

[auto-generated][maxmsp] Correct several signatures verified against Max for Live 8#74975
nemtsov wants to merge 1 commit into
DefinitelyTyped:masterfrom
nemtsov:fix/maxmsp-signatures-verified-m4l8

nemtsov commented May 10, 2026

Uh oh!

typescript-bot commented May 10, 2026 •

edited

Loading

Uh oh!

typescript-bot commented May 10, 2026

Uh oh!

nemtsov commented May 10, 2026

Uh oh!

twhiston commented May 10, 2026

Uh oh!

nemtsov commented May 10, 2026 •

edited

Loading

Uh oh!

twhiston commented May 10, 2026

Uh oh!

nemtsov commented May 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

nemtsov commented May 10, 2026

Changes

Test file

Verification

Uh oh!

typescript-bot commented May 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

1 package in this PR

Code Reviews

Status

Uh oh!

typescript-bot commented May 10, 2026

Uh oh!

nemtsov commented May 10, 2026

Uh oh!

twhiston commented May 10, 2026

Uh oh!

nemtsov commented May 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

twhiston commented May 10, 2026

Uh oh!

nemtsov commented May 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

typescript-bot commented May 10, 2026 •

edited

Loading

nemtsov commented May 10, 2026 •

edited

Loading