@kosdev-code/kos-asset-manager 0.0.1-next.20

package/README.md

@@ -0,0 +1,189 @@
+# @kosdev-code/kos-asset-manager
+
+Normalized access to images, video and other media that applications declare
+in their kab descriptors and the asset manager application serves.
+
+## Declaring assets in a ui project
+
+Put files under `src/assets/media` in the project. Everything below it is
+declared automatically, keyed by its path without the extension, so
+`src/assets/media/brand/logo-primary.svg` is the key `brand/logo-primary`.
+
+A key derived from a path breaks when the file moves, so pin the ones a ui
+depends on. Bindings live in the project's `.kos.json`, take a path relative
+to the media directory, and may capture with `{name}` or span folders with
+`**`:
+
+```json
+{
+  "kondra": {
+    "ui": {
+      "assets": {
+        "keys": {
+          "brand/logo-primary": "brand/logos/primary.svg",
+          "beverages/{name}": "drinks/{name}.svg",
+          "video/globe": "**/globe.mp4"
+        }
+      }
+    }
+  }
+}
+```
+
+Bindings can also sit beside the files they name, in a `.kosassets` file in
+any folder under the media directory. Its sources are relative to that
+folder while its keys stay absolute, so renaming or moving the folder
+carries the rules with it and no key changes:
+
+```
+# src/assets/media/brand/.kosassets
+brand/logo-primary = logos/primary.svg
+brand/{name}       = *.svg
+```
+
+A file takes the first key that claims it: `.kos.json`, then the nearest
+`.kosassets` walking up, then its own path. A binding that matches no file
+is reported during the build.
+
+Renaming a key is a breaking change for whoever uses it, so the old key can
+be kept alive alongside the new one:
+
+```json
+"entries": { "brand/logo-primary": { "aliases": ["brand/kos-logo"] } }
+```
+
+Lookups try the key first and then the aliases, which gives consumers time
+to catch up before the alias is dropped.
+
+Add the target that generates the declaration:
+
+```sh
+npx kos-assets init apps/my-app
+```
+
+This adds an `assets` target that runs after `descriptor`, and makes `zip`
+depend on it so the declaration is in the descriptor before the kab is built.
+To wire it by hand instead, add to the project's `project.json`:
+
+```json
+"assets": {
+  "command": "kos-assets build apps/my-app",
+  "dependsOn": ["descriptor"],
+  "inputs": [
+    "{projectRoot}/src/assets/media/**/*",
+    "{projectRoot}/.kos.json"
+  ],
+  "outputs": ["{workspaceRoot}/dist/{projectRoot}/descriptor.json"]
+}
+```
+
+and add `"assets"` to the `zip` target's `dependsOn`. The inputs and outputs
+matter: the declaration is written into a build output, so without them a
+restored build can be paired with a freshly scanned declaration and the kab
+ships assets it declares but does not contain.
+
+Video gets its thumbnail from an image that shares its key: drop
+`video/pour-loop.mp4` and `video/pour-loop-poster.png` in the same folder and
+they are paired automatically (`-poster` or `-still`). Name one explicitly
+when the convention doesn't fit:
+
+```json
+"entries": { "video/pour-loop": { "poster": "brand/hero-still" } }
+```
+
+The poster is an ordinary asset, so it is measured, preloaded and decoded
+like any other image. `wrapAsset('video/pour-loop').poster` is its url.
+
+Video is measured from its container for mp4, mov and m4v; anything else
+takes the dimensions of its poster, so a video reserves its space either
+way.
+
+Groups, tags and eager-loading are authored in the project's `.kos.json`.
+Groups and tags take patterns rather than lists of files -- `*` matches
+within a path segment and `**` across them -- and are expanded into concrete
+keys when the declaration is generated:
+
+```json
+{
+  "kondra": {
+    "ui": {
+      "assets": {
+        "tags": { "beverage-logo": ["beverages/**"] },
+        "groups": { "boot": ["brand/logo-primary", "beverages/**"] },
+        "entries": { "brand/logo-primary": { "preload": true } }
+      }
+    }
+  }
+}
+```
+
+A pattern that matches nothing is reported during the build.
+
+## Using assets in a ui
+
+```ts
+import { initAssets, wrapAsset, resolveAsset, preloadAssets } from '@kosdev-code/kos-asset-manager';
+
+// once while starting, naming the applications whose assets this ui uses
+await initAssets({ contexts: ['my.app.id'], preload: ['boot'] });
+
+const logo = wrapAsset('brand/logo-primary');
+<img src={logo.src} alt="" />
+
+// anywhere a url is expected
+element.style.backgroundImage = `url(${resolveAsset('brand/logo-primary')})`;
+
+// ready assets ahead of a screen that needs them
+await preloadAssets('checkout');
+```
+
+Sets of assets are selected rather than named, so adding a file to a folder
+is all it takes to include it:
+
+```ts
+await preloadAssets({ prefix: 'beverages/' });   // a folder
+await preloadAssets({ tag: 'beverage-logo' });   // a tag, across folders
+await preloadAssets({ type: 'video/' });         // by mime type
+
+listAssets({ tag: 'beverage-logo' }).map((asset) => asset.src);
+```
+
+Selector fields combine, so `{ prefix: 'brand/', type: 'image/svg+xml' }` is
+the svg files in that folder.
+
+## Preloading during bootstrap
+
+Preloading readies an image by fetching *and decoding* it, and holds the
+decoded image so the first paint has nothing left to do. Assets are served
+from the device over loopback, so the decode is the part that costs time --
+which is what makes images pop into view on lower powered hardware. Paying
+for it during a bootstrap sequence trades a couple of seconds at startup for
+screens that render immediately afterwards.
+
+```ts
+await preloadAssets({ prefix: 'beverages/' }, {
+  concurrency: 4,
+  onProgress: ({ done, total }) => setBootProgress(done / total),
+});
+```
+
+Assets are readied a few at a time, because a wide fan out on a slow device
+only thrashes. A single asset that cannot be readied is reported through
+`onProgress` with `ok: false` and never fails the sequence, so one bad file
+cannot stop a device from starting.
+
+Images are measured when the declaration is generated, so the space they
+take can be reserved and nothing reflows when they arrive:
+
+```tsx
+const logo = wrapAsset('brand/logo-primary');
+<img src={logo.src} width={logo.width} height={logo.height} alt="" />
+```
+
+`{ hold: true }` additionally keeps the bytes as an object url, which is
+worth it only when an asset must survive the content going away.
+`releaseAssets()` drops everything preloading is holding.
+
+Only the contexts named in `initAssets` are requested. Keys resolve in the
+default context (the first one declared) unless they name another, as in
+`other.app.id:brand/logo-primary`.

package/bin/kos-assets.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * Declares the ui assets of a kos project.
+ *
+ *   kos-assets build <projectRoot> [--out <descriptor.json>]
+ *   kos-assets init  <projectRoot>
+ *
+ * `build` scans a fixed directory in the project and merges a
+ * kondra.ui.assets block into the descriptor the kab is built from. `init`
+ * adds the target that runs it to the project.
+ */
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import {
+  SOURCE_DIR,
+  buildAssets,
+  readJson,
+  writeJson,
+} from './lib/declare-assets.mjs';
+
+const fail = (message) => {
+  console.error(`kos-assets: ${message}`);
+  process.exit(1);
+};
+
+const build = (projectRoot, out) => {
+  const descriptorPath = resolve(
+    out ?? join('dist', projectRoot, 'descriptor.json')
+  );
+  if (!existsSync(descriptorPath)) {
+    fail(
+      `no descriptor at ${descriptorPath} — run the descriptor target first, or pass --out`
+    );
+  }
+
+  const assets = buildAssets(resolve(projectRoot));
+  if (!assets) {
+    console.log(`kos-assets: no assets in ${join(projectRoot, ...SOURCE_DIR)}`);
+    return;
+  }
+
+  const descriptor = readJson(descriptorPath);
+  descriptor.kondra = {
+    ...descriptor.kondra,
+    ui: { ...descriptor.kondra?.ui, assets },
+  };
+  writeJson(descriptorPath, descriptor);
+  console.log(
+    `kos-assets: declared ${Object.keys(assets.entries).length} assets in ${descriptorPath}`
+  );
+};
+
+/**
+ * Add the assets target to a project and make the archive depend on it, so
+ * the block is in the descriptor before the kab is zipped.
+ */
+/**
+ * How the target should invoke this tool. A project that consumes the
+ * published package gets it from node_modules; the workspace that owns the
+ * source runs it from there, since nothing links a bin for a local lib.
+ */
+const invocation = () => {
+  const local = join(
+    'libs',
+    'kos-asset-manager-models',
+    'bin',
+    'kos-assets.mjs'
+  );
+  if (existsSync(resolve(local))) {
+    return `node ${local}`;
+  }
+  return 'npx kos-assets';
+};
+
+const init = (projectRoot) => {
+  const path = resolve(projectRoot, 'project.json');
+  if (!existsSync(path)) {
+    fail(`no project.json in ${projectRoot}`);
+  }
+
+  const project = readJson(path);
+  project.targets = project.targets ?? {};
+  // the declaration is written into a build output, so nx needs to know what
+  // it reads and what it produces — otherwise a restored build can be paired
+  // with a freshly scanned declaration and the kab ships a mismatch
+  project.targets.assets = {
+    command: `${invocation()} build ${projectRoot}`,
+    dependsOn: ['descriptor'],
+    inputs: [
+      `{projectRoot}/${SOURCE_DIR.join('/')}/**/*`,
+      '{projectRoot}/.kos.json',
+    ],
+    outputs: ['{workspaceRoot}/dist/{projectRoot}/descriptor.json'],
+  };
+
+  const zip = project.targets.zip;
+  if (zip && !(zip.dependsOn ?? []).includes('assets')) {
+    zip.dependsOn = [...(zip.dependsOn ?? []), 'assets'];
+  }
+
+  writeJson(path, project);
+  console.log(`kos-assets: added the assets target to ${path}`);
+};
+
+const [command, projectRoot, ...rest] = process.argv.slice(2);
+if (!command || !projectRoot) {
+  fail('usage: kos-assets <build|init> <projectRoot> [--out <descriptor.json>]');
+}
+
+const outIndex = rest.indexOf('--out');
+const out = outIndex === -1 ? undefined : rest[outIndex + 1];
+
+switch (command) {
+  case 'build':
+    build(projectRoot, out);
+    break;
+  case 'init':
+    init(projectRoot);
+    break;
+  default:
+    fail(`unknown command: ${command}`);
+}