@makefully/dutifully 1.21.2 → 1.22.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 1.22.0
+
+- Select a subset of service listings via optional job `id` and top-level `only` (`cheer -service packfully -only heroes,ui`).
+
 ## 1.21.2
 
 - Yap poll uses `/status` then download; while pending, tails `/logs` for live Cheerfully worker output.

package/README.md

@@ -42,6 +42,41 @@ cheerfully({
 });
 ```
 
+### Selecting listings (`id` + `only`)
+
+Each service entry in `cheerfully.json` is an array of jobs (listings). Give any job an optional `id` string (unique within that service) to target it without running the whole array:
+
+```javascript
+{
+    "packfully": [{
+        "id": "heroes",
+        "src": "./sprites/heroes/",
+        "output": "./atlases/",
+        "options": { "prefix": "heroes" }
+    }, {
+        "id": "ui",
+        "src": "./sprites/ui/",
+        "output": "./atlases/",
+        "options": { "prefix": "ui" }
+    }]
+}
+```
+
+Then run a subset from the CLI or from Node:
+
+```bash
+cheer -service packfully -only heroes,ui
+```
+
+```javascript
+cheerfully({
+    service: 'packfully',
+    only: ['heroes', 'ui']   // or only: 'heroes,ui'
+});
+```
+
+Omit `only` to run every listing for that service (unchanged). Jobs without an `id` still run in that case; they cannot be selected when `only` is set. Unknown or duplicate ids fail with a clear error. Per-job difference skipping still applies to whichever listings you select. The `id` field is for client selection; Cheerfully ignores it on the server.
+
 ### Say (spoken notifications)
 
 `say` generates short spoken phrases through Cheerfully's ElevenLabs service, caches the audio under `.cache/tts/`, and plays it locally via `node-web-audio-api`. Use it from npm scripts instead of wiring ElevenLabs into the consuming project:
@@ -118,6 +153,7 @@ This image-to-atlas service packs PNG/JPG/WebP sprites into texture atlases and
 ```javascript
 {
     "packfully": [{
+        "id": "packed",
         "format": "texturepacker",
         "src": "./example/sprites/",
         "output": "./example/atlases/",

package/cheer.js

@@ -34,4 +34,7 @@ const
         return cmds;
     };
 
-cheer(getArgsAsObj());
+cheer(getArgsAsObj()).catch((err) => {
+    console.error(err.message || err);
+    process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@makefully/dutifully",
-    "version": "1.21.2",
+    "version": "1.22.0",
     "description": "Client tools for Cheerfully service.",
     "main": "./src/index.js",
     "bin": {

package/src/helpers/filterJobs.js

@@ -0,0 +1,118 @@
+/**
+ * Select a subset of cheerfully.json job listings by optional job `id`.
+ */
+
+/**
+ * @param {unknown} only
+ * @returns {string[]|null} null means no filter; non-empty array means filter
+ * @throws {Error} when `only` is present but yields no ids (e.g. bare `-only`)
+ */
+const normalizeOnly = (only) => {
+    if (only === undefined || only === null || only === false) {
+        return null;
+    }
+
+    if (only === true) {
+        throw new Error('`-only` requires one or more job ids (e.g. -only heroes,ui).');
+    }
+
+    let raw;
+
+    if (typeof only === 'string') {
+        raw = only.split(',');
+    } else if (Array.isArray(only)) {
+        raw = only;
+    } else {
+        throw new Error(`Invalid \`only\` value: expected string or string[], got ${typeof only}.`);
+    }
+
+    const
+        ids = raw
+            .map((id) => String(id ?? '').trim())
+            .filter((id) => id.length > 0);
+
+    if (!ids.length) {
+        throw new Error('`-only` requires one or more job ids (e.g. -only heroes,ui).');
+    }
+
+    return ids;
+};
+
+/**
+ * Build a map from job id → original array index. Hard-errors on duplicate ids.
+ *
+ * @param {object[]} configs
+ * @returns {Map<string, number>}
+ */
+const indexJobsById = (configs) => {
+    const
+        byId = new Map();
+
+    for (let i = 0; i < configs.length; i++) {
+        const
+            job = configs[i],
+            jobId = job?.id;
+
+        if (jobId === undefined || jobId === null || jobId === '') {
+            continue;
+        }
+
+        const
+            key = String(jobId);
+
+        if (byId.has(key)) {
+            throw new Error(
+                `Duplicate job id "${key}" at indices ${byId.get(key)} and ${i}. Job ids must be unique within a service.`
+            );
+        }
+
+        byId.set(key, i);
+    }
+
+    return byId;
+};
+
+/**
+ * @param {object[]} configs
+ * @param {string[]|null} onlyIds from normalizeOnly
+ * @returns {{jobs: object[], indices: number[]}}
+ */
+const filterJobsById = (configs, onlyIds) => {
+    if (!onlyIds) {
+        return {
+            jobs: configs,
+            indices: configs.map((_, i) => i)
+        };
+    }
+
+    const
+        byId = indexJobsById(configs),
+        known = [...byId.keys()].sort(),
+        jobs = [],
+        indices = [];
+
+    for (const wanted of onlyIds) {
+        if (!byId.has(wanted)) {
+            const
+                knownList = known.length ? known.join(', ') : '(none)';
+
+            throw new Error(
+                `Unknown job id "${wanted}". Known ids: ${knownList}.`
+            );
+        }
+
+        const
+            index = byId.get(wanted);
+
+        jobs.push(configs[index]);
+        indices.push(index);
+    }
+
+    return {jobs, indices};
+};
+
+module.exports = {
+    normalizeOnly,
+    filterJobsById,
+    indexJobsById
+};

package/src/index.js

@@ -17,15 +17,19 @@ const
         translate: require('./classes/Translate')
     },
     getJSON = require('./helpers/getJSON'),
+    {normalizeOnly, filterJobsById} = require('./helpers/filterJobs'),
     send = async function (contents) {
         const
             {id, service} = contents,
-            configs = Array.isArray(contents[service]) ? contents[service] : [contents[service]];
+            configs = Array.isArray(contents[service]) ? contents[service] : [contents[service]],
+            onlyIds = normalizeOnly(contents.only),
+            {jobs, indices} = filterJobsById(configs, onlyIds),
+            {length} = configs;
 
-        for (let index = 0; index < configs.length; index++) {
+        for (let i = 0; i < jobs.length; i++) {
             const
-                config = configs[index],
-                {length} = configs;
+                config = jobs[i],
+                index = indices[i];
 
             if (!config) {
                 console.warn(`Empty configuration for "${service}" service.`);
@@ -58,7 +62,7 @@ const cheer = async (cmdArgs) => {
         config = await getJSON('./cheerfully.json') ?? {},
         env = await getJSON('./env-cheerfully.json') ?? {};
 
-    send({
+    await send({
         id: `${package.name}-${package.version}`,
         package,
         ...config,