rockstar-strudel 1.0.7 → 1.0.10

package/README.md

@@ -75,6 +75,39 @@ const shifted = await melody.rerun(62)
 const shiftedAgain = await shifted.rerun(([prevRoot]) => [prevRoot + 2])
 ```
 
+### Using `to_base()` for melodic number conversion
+
+Convert output numbers to different bases and feed them into a Strudel sequence:
+
+```js
+const { init, rockstar, rockstar_pro, to_base } = await import('https://esm.sh/rockstar-strudel')
+
+// Pre-warm the WASM engine while other code loads (optional but recommended)
+await init()
+
+// Run a Rockstar program
+const prog = await rockstar_pro`
+  Papa was a rolling stone
+  (Wherever he laid his hat)
+  (was his home)
+  (And when he died)
+  (All he left us was alone)
+  Say Papa
+  Build up Papa
+  Scream Papa
+`
+
+samples('shabda/speech:'+prog.speech.join(','))
+
+$: s(slowcat(prog.speech.slice(0,5)).degradeBy(.9))
+
+$: note(seq(to_base(prog.output, 10).flat(2))
+  .slow("<4 2 4>")
+  .scale("C:major")
+)
+.sound("piano").every(4, rev)
+```
+
 
 ### Template interpolations
 
@@ -109,6 +142,8 @@ Tagged-template function with richer parallel output views:
 - `output`: numeric-first values (`number` or nested numeric arrays).
 - `mixed_output`: mixed typed values with words preserved.
 - `text_output`: fully stringified values for text/speech use.
+- `error`: `null` on success, otherwise `{ name, message }` describing a runtime
+  failure from the underlying runner.
 - `speech`: sanitized line tokens derived from source code for Shabda speech
   sample lookup (for example `samples('shabda/speech:'+prog.speech.join(','))`).
 - `templateValues`: the interpolation values used for this run.
@@ -121,6 +156,24 @@ emitted line.
 For JSON-style list output (for example `[ "012" ]`), all views parse the same
 structure, and `output` resolves that case to `[12]`.
 
+When a runtime error occurs, `rockstar_pro` returns the same object shape with
+`output`, `mixed_output`, and `text_output` left as `[]`, while `error` carries
+the failure details.
+
+Example error handling:
+
+```js
+const prog = await rockstar_pro`
+  pri nt "Hello, World"
+`
+
+if (prog.error) {
+  console.error(`Rockstar runtime error: ${prog.error.message}`)
+} else {
+  note(seq(prog.output)).sound("piano")
+}
+```
+
 ### `init([dotnetUrl])` → `Promise<void>`
 
 Pre-loads the WASM engine.  Optionally accepts a custom `dotnet.js` URL (see
@@ -148,6 +201,16 @@ an ellipsis (`...` or `…`) introduces the decimal separator.
 Parses one raw callback line into a dual-view structure used by
 `rockstar_pro` (`raw`, `output`, `poetic`). Exported for testing.
 
+### `to_base(number, base)` → `array | array[]`
+
+Converts a number or array of numbers to the specified base (2–36), returning
+an array of digits or an array of digit arrays.  Useful for converting Rockstar
+output into melodic sequences via Strudel's `seq()`.
+
+Examples:
+- `to_base(1344, 10)` → `[1, 3, 4, 4]`
+- `to_base([1344, 23], 16)` → `[[5, 4, 0], [1, 7]]`
+
 ---
 
 ## How it works

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rockstar-strudel",
-  "version": "1.0.7",
+  "version": "1.0.10",
   "description": "Run Rockstar lang programs via the Starship WASM engine, returning output as a JS array. Designed for use in the strudel.cc live-coding REPL.",
   "type": "module",
   "main": "./src/index.js",

package/src/index.js

@@ -69,6 +69,27 @@ export function isTrustedUrl(url) {
  */
 let _runnerPromise = null;
 
+/**
+ * Test-only seam: replace the cached runner promise.
+ * This allows unit tests to validate `rockstar` / `rockstar_pro`
+ * behavior without loading the WASM runtime.
+ *
+ * @param {Promise<object> | null} runnerPromise
+ * @returns {void}
+ */
+export function __setRunnerPromiseForTests(runnerPromise) {
+  _runnerPromise = runnerPromise;
+}
+
+/**
+ * Test-only helper: clear the cached runner promise.
+ *
+ * @returns {void}
+ */
+export function __resetRunnerForTests() {
+  _runnerPromise = null;
+}
+
 /**
  * Pre-load the Rockstar WASM engine.
  *
@@ -496,6 +517,7 @@ export async function rockstar_pro(strings, ...values) {
   const output = [];
   const mixed_output = [];
   const text_output = [];
+  let error = null;
   const lines = code.split('\n')
   const speech = lines.map((x) => x.toLowerCase()
   .trim()
@@ -503,23 +525,29 @@ export async function rockstar_pro(strings, ...values) {
   .replace(/\W/g, ''))
   .filter((x)=> x.length);
 
-  console.log(`samples('shabda/speech:'+prog.speech.join(','))`)
-
-  await runner.Run(
-    code,
-    (line) => {
-      raw_output.push(line);
+  //console.log(`samples('shabda/speech:'+prog.speech.join(','))`)
 
-      const parsed = parseOutputLine(line);
-      if (!parsed) return;
-
-      output.push(parsed.output);
-      mixed_output.push(parsed.mixed_output);
-      text_output.push(parsed.text_output);
-    },
-    /* stdin */ '',
-    /* args  */ ''
-  );
+  try {
+    await runner.Run(
+      code,
+      (line) => {
+        raw_output.push(line);
+
+        const parsed = parseOutputLine(line);
+        if (!parsed) return;
+
+        output.push(parsed.output);
+        mixed_output.push(parsed.mixed_output);
+        text_output.push(parsed.text_output);
+      },
+      /* stdin */ '',
+      /* args  */ ''
+    );
+  } catch (err) {
+    error = err instanceof Error
+      ? { name: err.name, message: err.message }
+      : { name: 'Error', message: String(err) };
+  }
 
   const unsupported = (featureName) => {
     throw new Error(
@@ -535,6 +563,7 @@ export async function rockstar_pro(strings, ...values) {
     output,
     mixed_output,
     text_output,
+    error,
     speech,
     rerun: (...nextArgs) => {
       const nextValues = resolveRerunValues(values, ...nextArgs);
@@ -545,3 +574,20 @@ export async function rockstar_pro(strings, ...values) {
     listFunctions: () => unsupported('listFunctions()'),
   };
 }
+
+export const to_base = function (number, base) {
+    const convertOne = function (value) {
+        let digit = [];
+        while (value > 0) {
+            digit.unshift(value % base);
+            value = Math.floor(value / base);
+        }
+        return digit;
+    };
+
+    if (Array.isArray(number)) {
+        return number.map(convertOne);
+    }
+
+    return convertOne(number);
+}

package/test/rockstar.test.js

@@ -7,14 +7,18 @@
  * Run with:  npm test
  */
 
-import { describe, it } from 'node:test';
+import { beforeEach, describe, it } from 'node:test';
 import assert from 'node:assert/strict';
 import {
+  __resetRunnerForTests,
+  __setRunnerPromiseForTests,
   buildSource,
   coerce,
   isTrustedUrl,
   parsePoeticNumber,
   parseOutputLine,
+  rockstar,
+  rockstar_pro,
   resolveRerunValues,
 } from '../src/index.js';
 
@@ -286,3 +290,123 @@ describe('resolveRerunValues', () => {
     assert.deepEqual(next, [99]);
   });
 });
+
+// ─── example-program output shaping (non-WASM) ────────────────────────────
+
+describe('example Rockstar program outputs (non-WASM shaping)', () => {
+  const collectViews = (rawLines) => {
+    const output = [];
+    const mixed_output = [];
+    const text_output = [];
+
+    for (const line of rawLines) {
+      const parsed = parseOutputLine(line);
+      if (!parsed) continue;
+      output.push(parsed.output);
+      mixed_output.push(parsed.mixed_output);
+      text_output.push(parsed.text_output);
+    }
+
+    return { output, mixed_output, text_output };
+  };
+
+  it('matches the two-line numeric output shape from the Papa + Scream example', () => {
+    const parsed = collectViews(['175\n', '179\n']);
+    assert.deepEqual(parsed.output, [175, 179]);
+  });
+
+  it('matches rockstar numeric output for a single Say line', () => {
+    const parsed = collectViews(['175\n']);
+    assert.deepEqual(parsed.output, [175]);
+  });
+
+  it('matches rockstar_pro numeric output for a single Say line', () => {
+    const parsed = collectViews(['175\n']);
+    assert.deepEqual(parsed.output, [175]);
+  });
+
+  it('matches successive numeric updates from the He was with him example', () => {
+    const parsed = collectViews(['175\n', '350\n']);
+    assert.deepEqual(parsed.output, [175, 350]);
+  });
+
+  it('keeps AC/DC-like output text in mixed/text views', () => {
+    const parsed = collectViews(['AD/DC\n']);
+    assert.deepEqual(parsed.mixed_output, ['AD/DC']);
+    assert.deepEqual(parsed.text_output, ['AD/DC']);
+  });
+
+  it('produces empty parallel views when no lines are emitted', () => {
+    const parsed = collectViews([]);
+    assert.deepEqual(parsed.output, []);
+    assert.deepEqual(parsed.mixed_output, []);
+    assert.deepEqual(parsed.text_output, []);
+  });
+});
+
+// ─── rockstar / rockstar_pro wrappers via mocked runner ───────────────────
+
+describe('rockstar wrappers (mocked runner)', () => {
+  beforeEach(() => {
+    __resetRunnerForTests();
+  });
+
+  it('rockstar returns numeric-first output values', async () => {
+    const fakeRunner = {
+      async Run(_code, onLine) {
+        onLine('175\n');
+      },
+    };
+    __setRunnerPromiseForTests(Promise.resolve(fakeRunner));
+
+    const out = await rockstar`
+      Papa was a rolling stone
+      Say Papa
+    `;
+
+    assert.deepEqual(out, [175]);
+  });
+
+  it('rockstar_pro returns parallel output views', async () => {
+    const fakeRunner = {
+      async Run(_code, onLine) {
+        onLine('175\n');
+        onLine('350\n');
+      },
+    };
+    __setRunnerPromiseForTests(Promise.resolve(fakeRunner));
+
+    const out = await rockstar_pro`
+      Papa was a rolling stone
+      Say Papa
+      He was with him
+      Say Papa
+    `;
+
+    assert.deepEqual(out.output, [175, 350]);
+    assert.deepEqual(out.mixed_output, [175, 350]);
+    assert.deepEqual(out.text_output, ['175', '350']);
+    assert.equal(out.error, null);
+  });
+
+  it('rockstar_pro preserves [] outputs and exposes an error field on runtime failure', async () => {
+    const fakeRunner = {
+      async Run() {
+        throw new Error('Parse error near "pri nt"');
+      },
+    };
+    __setRunnerPromiseForTests(Promise.resolve(fakeRunner));
+
+    const out = await rockstar_pro`
+      pri nt "Hello, World"
+    `;
+
+    assert.deepEqual(out.output, []);
+    assert.deepEqual(out.mixed_output, []);
+    assert.deepEqual(out.text_output, []);
+    assert.deepEqual(out.error, {
+      name: 'Error',
+      message: 'Parse error near "pri nt"',
+    });
+  });
+});