@genrojs/bag 0.10.1

package/src/browser.js

@@ -0,0 +1,7 @@
+import * as TYTX from '@genrojs/tytx';
+
+TYTX.setDecimalLibrary('number');
+
+export {TYTX};
+export * from './index.js';
+export const version = '0.7.0';

package/src/devtools/html-repr.css

@@ -0,0 +1,69 @@
+/* Theme and layout tokens. */
+:root{color-scheme:light;--bg:#fff;--text:#25313a;--muted:#77818c;--line:#e5e8eb;--focus:#2878b8}
+@media(prefers-color-scheme:dark){:root:not([data-theme="light"]){color-scheme:dark;--bg:#171a1d;--text:#d5dbe0;--muted:#8f9aa4;--line:#30363c;--focus:#72b9ef}}
+:root[data-theme="dark"]{color-scheme:dark;--bg:#171a1d;--text:#d5dbe0;--muted:#8f9aa4;--line:#30363c;--focus:#72b9ef}
+.bag-view{--attribute-lane:190px;--lane-gap:10px;--indent:8px;background:var(--bg);color:var(--text);font:13px/1.4 system-ui,sans-serif;min-width:0}
+.bag-nodes{list-style:none;margin:0;padding:0}
+.bag-node{display:grid;grid-template-columns:minmax(0,1fr) var(--attribute-lane);column-gap:var(--lane-gap);align-items:start;min-width:0}
+.bag-row{grid-column:1;display:grid;grid-template-columns:max-content minmax(90px,32%) minmax(0,1fr) auto;align-items:center;gap:2px;min-height:20px;padding:0 6px;min-width:0}
+.bag-row:hover{background:#ffffff30}
+.bag-label{font-weight:500;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;padding-right:8px;color:#4d4940}
+.bag-value{font:12px/1.45 ui-monospace,monospace;white-space:pre-wrap;overflow-wrap:anywhere;min-width:0;color:#38352e}
+.type-badge{display:inline-flex;align-items:center;justify-content:center;justify-self:start;box-sizing:border-box;min-width:12px;height:12px;padding:0 2px;background:#888;color:#fff;border-radius:2px;font:500 8px/12px system-ui,sans-serif}
+.node-tag{font-size:11px;font-style:italic;font-weight:400;margin-left:5px;white-space:nowrap}
+.bag-meta{display:flex;justify-content:flex-end;align-items:center;min-width:0;font-size:11px}
+
+/* Bag surfaces stop before the fixed attribute lane. */
+.bag-branch{position:relative;isolation:isolate;border-radius:5px;margin:3px 0;--bag-surface:#f1f1f1;--right-inset:0px}
+.bag-depth-1{--bag-surface:#e7e7e7}
+.bag-branch::before{content:"";position:absolute;inset:0 calc(var(--attribute-lane) + var(--lane-gap) + var(--right-inset)) 0 0;z-index:-1;background:var(--bag-surface);border:1px solid #d5d5d5;border-radius:5px;pointer-events:none}
+.bag-nodes .bag-nodes>.bag-branch{--right-inset:var(--indent)}
+.bag-toggle{grid-column:1;margin-right:var(--right-inset);background:#707070;border-radius:4px;min-width:0}
+.bag-toggle>summary{display:flex;align-items:center;position:relative;min-height:20px;padding:0 6px 0 22px;color:#fff;border-radius:4px}
+.bag-toggle>summary:hover{background:#646464}
+.bag-toggle>summary .bag-label{padding:0;color:inherit;flex:0 1 auto}
+.bag-branch-name{display:flex;align-items:center;gap:5px;min-width:0}
+.bag-count{display:inline-flex;align-items:center;justify-content:center;box-sizing:border-box;flex:none;min-width:14px;height:13px;padding:0 3px;border-radius:4px;background:#fff;color:#555;font:500 9px/12px system-ui,sans-serif}
+.bag-branch>.bag-nodes{grid-column:1/-1;padding:3px 0 5px var(--indent)}
+.bag-empty,.bag-cycle{grid-column:1/-1;color:#796f5c;font-size:12px;font-style:italic;margin:5px 0 7px 22px}
+.bag-branch:has(>.bag-toggle:not([open]))>:is(.bag-nodes,.bag-empty,.bag-cycle){display:none}
+
+/* Native disclosures share one centered, outlined arrow. */
+.bag-view summary{cursor:pointer;list-style:none}
+.bag-view summary::-webkit-details-marker{display:none}
+.bag-view summary:focus-visible{outline:2px solid var(--focus);outline-offset:-2px;border-radius:2px}
+:is(.bag-toggle,.bag-attributes)>summary::before{content:"";position:absolute;left:5px;top:50%;width:12px;height:12px;background:center/12px 12px no-repeat url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12'%3E%3Cpath d='M4 2 L8 6 L4 10' fill='none' stroke='%23fff' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E");transform:translateY(-50%);transition:transform .12s ease}
+:is(.bag-toggle,.bag-attributes)[open]>summary::before{transform:translateY(-50%) rotate(90deg)}
+
+/* Attributes use a separate, consistently aligned olive panel. */
+.bag-attributes{grid-column:2;grid-row:1;min-width:0;margin:1px 0 2px;border-radius:5px;overflow:hidden}
+.bag-attributes>summary{position:relative;box-sizing:border-box;height:17px;line-height:17px;padding:0 7px 0 20px;background:#7d8559;color:#fff;border-radius:5px;font-size:10px}
+.bag-attributes>summary:hover{background:#6e764d}
+.bag-attributes[open]>summary{border-radius:5px 5px 0 0}
+.bag-attribute-count{margin-left:3px}
+.bag-attributes>dl{display:grid;gap:1px;box-sizing:border-box;margin:0;padding:4px 8px 5px 21px;background:#f3f4e7;border:1px solid #dce0c5;border-top:0;border-radius:0 0 5px 5px}
+.bag-attr{display:grid;grid-template-columns:minmax(0,1fr) minmax(40px,1fr);gap:8px;line-height:16px}
+.bag-attr dt{display:grid;grid-template-columns:max-content minmax(0,1fr);align-items:center;gap:2px;color:#69704e;font-size:11px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.bag-attr dd{margin:0;min-width:0}
+.bag-attr code{font:11px/1.4 ui-monospace,monospace;color:#3f452e;overflow-wrap:anywhere}
+
+/* Resolver details are inert: expanding never invokes a callback. */
+.bag-resolver{position:relative;justify-self:end;align-self:start;z-index:3;font-size:10px;color:#675829}
+.bag-branch>.bag-resolver{grid-column:1;grid-row:1;margin:2px calc(var(--right-inset) + 5px) 0 0}
+.bag-branch:has(>.bag-resolver)>.bag-toggle{padding-right:110px}
+.bag-resolver>summary{background:#fff1bb;color:#675829;border:1px solid #e8d997;border-radius:4px;padding:0 5px;font:10px/15px system-ui,sans-serif}
+.bag-resolver>dl{box-sizing:border-box;width:220px;max-width:100%;margin:3px 0 0;padding:7px;background:#fff9df;color:#51482d;border:1px solid #e8d997;border-radius:4px}
+.bag-resolver>dl>div{display:grid;grid-template-columns:90px 1fr;gap:8px;line-height:19px}
+.bag-resolver dt,.bag-resolver dd{margin:0;overflow-wrap:anywhere}
+.bag-no-types .bag-row{grid-template-columns:minmax(90px,32%) minmax(0,1fr) auto}
+.bag-no-types .bag-attr dt{display:block}
+@media(max-width:560px){
+ .bag-view{--attribute-lane:145px;--lane-gap:6px;--indent:5px}
+ .bag-row{grid-template-columns:max-content minmax(50px,1fr);padding-right:3px}
+ .bag-value{grid-column:2;font-size:11px}
+ .bag-label{white-space:normal}
+ .bag-meta{grid-column:2}
+ .bag-attr{grid-template-columns:1fr}
+ .bag-no-types .bag-row{grid-template-columns:minmax(50px,1fr) minmax(0,1fr)}
+ .bag-no-types .bag-value{grid-column:auto}
+}

package/src/devtools/html-repr.js

@@ -0,0 +1,78 @@
+// Copyright 2026 Softwell S.r.l. - SPDX-License-Identifier: Apache-2.0
+import { toTytx } from '@genrojs/tytx';
+
+const TYPE_NAMES = {T:'Text',L:'Integer',R:'Float',N:'Decimal',B:'Boolean',D:'Date',H:'Time',HZ:'Time with timezone',DH:'Datetime',DHZ:'Datetime with timezone',NN:'Null',RAW:'Bytes',JS:'JSON',X:'Bag'};
+
+/** Return an inert HTML fragment for a Bag without resolving or mutating it. */
+export function htmlRepr(bag, options = {}) {
+  const {openDepth = 0, className = '', openAttributes = false, showTypes = true, title = 'Bag'} = options;
+  const ancestors = new Set();
+  const escape = value => String(value).replaceAll('&','&amp;').replaceAll('<','&lt;').replaceAll('>','&gt;').replaceAll('"','&quot;').replaceAll("'",'&#39;');
+  const isBag = value => value !== null && typeof value === 'object' && typeof value.getNodes === 'function';
+
+  function tytxInfo(value) {
+    let dtype, text;
+    try {
+      const encoded = toTytx(value);
+      if (typeof value === 'string') { dtype = 'T'; text = value; }
+      else if (value == null) { dtype = 'NN'; text = String(value); }
+      else if (typeof value === 'boolean') { dtype = 'B'; text = encoded; }
+      else if (typeof value === 'number') { dtype = Number.isInteger(value) ? 'L' : 'R'; text = String(value); }
+      else {
+        const suffix = typeof encoded === 'string' && encoded.match(/::([A-Z][A-Z0-9]*)$/);
+        dtype = suffix ? suffix[1] : 'JS';
+        text = suffix ? encoded.slice(0, -suffix[0].length) : encoded;
+      }
+    } catch { dtype = 'JS'; text = '[unserializable value]'; }
+    return {dtype, text:String(text), name:TYPE_NAMES[dtype] || 'TYTX value'};
+  }
+  function badge(dtype, name) {
+    if (!showTypes) return '';
+    const title = `${dtype} — ${name}`;
+    return `<span class="type-badge" data-dtype="${escape(dtype)}" title="${escape(title)}" aria-label="${escape(title)}">${escape(dtype)}</span>`;
+  }
+  function attributes(attrs) {
+    const entries = Object.entries(attrs || {});
+    if (!entries.length) return '';
+    const rows = entries.map(([key,value]) => {
+      const info = tytxInfo(value);
+      return `<div class="bag-attr"><dt>${badge(info.dtype,info.name)}<span>${escape(key)}</span></dt><dd><code>${escape(info.text)}</code></dd></div>`;
+    }).join('');
+    return `<details class="bag-attributes"${openAttributes ? ' open' : ''}><summary aria-label="${entries.length} attributes"><span class="bag-attribute-count">${entries.length}</span></summary><dl>${rows}</dl></details>`;
+  }
+  function renderBag(current, depth, nodes) {
+    if (ancestors.has(current)) return '<p class="bag-cycle" role="note">↻ circular reference</p>';
+    ancestors.add(current);
+    const html = nodes.length ? `<ol class="bag-nodes">${nodes.map(node => renderNode(node,depth)).join('')}</ol>` : '<p class="bag-empty">Empty Bag</p>';
+    ancestors.delete(current);
+    return html;
+  }
+  function resolverPanel(resolver) {
+    if (!resolver) return '';
+    const parameters = {cacheTime:resolver.cacheTime, readOnly:resolver.readOnly,
+      ...(options.resolverParameters ? options.resolverParameters(resolver) : {})};
+    const rows = Object.entries(parameters).map(([key,value]) => {
+      if (typeof value === 'function') {
+        return `<div><dt>${escape(key)}</dt><dd><code>${escape(value.name || '(anonymous)')}()</code></dd></div>`;
+      }
+      const info = tytxInfo(value);
+      return `<div><dt>${escape(key)}</dt><dd>${badge(info.dtype,info.name)} ${escape(info.text)}</dd></div>`;
+    }).join('');
+    return `<details class="bag-resolver" title="Static view: resolver was not evaluated"><summary>${escape(resolver.constructor.name)}</summary><dl>${rows}</dl></details>`;
+  }
+  function renderNode(node, depth) {
+    const value = node.staticValue;
+    const resolverBadge = resolverPanel(node.resolver);
+    const attrs = attributes(node.attr);
+    const tag = node.nodeTag ? `<span class="node-tag">${escape(node.nodeTag)}</span>` : '';
+    if (isBag(value)) {
+      const nodes = value.getNodes();
+      const count = nodes.length;
+      return `<li class="bag-node bag-branch bag-depth-${depth % 2}"><details class="bag-toggle"${depth < openDepth ? ' open' : ''}><summary><span class="bag-branch-name"><span class="bag-label">${escape(node.label)}</span><span class="bag-count" aria-label="${count} nodes">${count}</span>${tag}</span></summary></details>${resolverBadge}${attrs}${renderBag(value,depth + 1,nodes)}</li>`;
+    }
+    const info = tytxInfo(value);
+    return `<li class="bag-node bag-leaf"><div class="bag-row">${badge(info.dtype,info.name)}<span class="bag-label">${escape(node.label)}${tag}</span><code class="bag-value">${escape(info.text)}</code><span class="bag-meta">${resolverBadge}</span></div>${attrs}</li>`;
+  }
+  if (!isBag(bag)) throw new TypeError('htmlRepr expects a Bag-like object with getNodes()');
+  return `<div class="${escape(['bag-view',showTypes ? '' : 'bag-no-types',className].filter(Boolean).join(' '))}"><ol class="bag-nodes">${renderNode({label:title, staticValue:bag, attr:{}, resolver:null, nodeTag:null},0)}</ol></div>`;
+}

package/src/devtools/index.js

@@ -0,0 +1 @@
+export { htmlRepr } from './html-repr.js';

package/src/index.js

@@ -0,0 +1,9 @@
+// Copyright 2025 Softwell S.r.l. - SPDX-License-Identifier: Apache-2.0
+
+export { Bag, BagException } from './bag.js';
+export { BagNode } from './bag-node.js';
+export { BagNodeContainer } from './bag-node-container.js';
+export { BagResolver, BagCbResolver, RETRY_POLICIES } from './resolver.js';
+export { UrlResolver, UuidResolver, StorageResolver } from './resolvers/index.js';
+
+export { BagSerializationError, OpaqueResolver, registerResolver } from './resolver-wire.js';

package/src/resolver-wire.js

@@ -0,0 +1,128 @@
+// Copyright 2026 Softwell S.r.l. - SPDX-License-Identifier: Apache-2.0
+
+import { BagResolver } from './resolver.js';
+
+/**
+ * Python-compatible resolver descriptions for TYTX, JSON and XML.
+ * Registration is explicit: adapters translate parameters between runtimes.
+ * Decoders must construct inert BagResolvers, never perform resolution or I/O.
+ * Unknown descriptions and signed tokens remain opaque and travel unchanged.
+ * A browser does not authenticate signed tokens; verification belongs to the
+ * server. Signed tokens are never used to instantiate a client-side resolver.
+ */
+const MARKER = '::RSLV:';
+const registrations = new Map();
+const classes = new Map();
+const opaquePayloads = new WeakMap();
+
+export class BagSerializationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BagSerializationError';
+    }
+}
+
+/** A server resolver description that can travel, but cannot execute locally. */
+export class OpaqueResolver extends BagResolver {
+    constructor(payload) {
+        super({ asBag: false });
+        opaquePayloads.set(this, payload);
+    }
+
+    get payload() {
+        return opaquePayloads.get(this);
+    }
+
+    load() {
+        throw new BagSerializationError('This resolver is opaque; local execution is unavailable');
+    }
+}
+
+/**
+ * Register a JS counterpart for a Python module/class pair.
+ * encode(resolver) returns {args: [], kwargs: {}}; decode({args, kwargs})
+ * returns an inert instance of cls. Names are wire identifiers, not imports.
+ */
+export function registerResolver(cls, { module, name, encode, decode }) {
+    if (!(cls.prototype instanceof BagResolver) || cls === OpaqueResolver
+        || typeof module !== 'string' || !module || typeof name !== 'string' || !name
+        || typeof encode !== 'function' || typeof decode !== 'function') {
+        throw new TypeError('registerResolver requires a BagResolver subclass, module, name and adapters');
+    }
+    const key = JSON.stringify([module, name]);
+    if (registrations.has(key) && registrations.get(key).cls !== cls) {
+        throw new TypeError(`Resolver ${module}.${name} is already registered`);
+    }
+    if (classes.has(cls) && classes.get(cls).key !== key) {
+        throw new TypeError('A resolver class cannot own two wire identities');
+    }
+    const entry = { cls, module, name, encode, decode, key };
+    registrations.set(key, entry);
+    classes.set(cls, entry);
+}
+
+function validateDescription(data) {
+    if (!data || typeof data !== 'object' || Array.isArray(data)
+        || typeof data.resolver_module !== 'string' || typeof data.resolver_class !== 'string'
+        || !Array.isArray(data.args ?? []) || !data.kwargs
+        || typeof data.kwargs !== 'object' || Array.isArray(data.kwargs)) {
+        throw new BagSerializationError('Invalid resolver description');
+    }
+}
+
+function validateJson(value, parents = new Set()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') return;
+    if (typeof value === 'number' && Number.isFinite(value)) return;
+    if (typeof value !== 'object' || parents.has(value)
+        || (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype
+            && Object.getPrototypeOf(value) !== null)) {
+        throw new BagSerializationError('Resolver parameters must be JSON data; callbacks cannot travel');
+    }
+    parents.add(value);
+    for (const child of Object.values(value)) validateJson(child, parents);
+    parents.delete(value);
+}
+
+export function encodeResolver(resolver) {
+    if (opaquePayloads.has(resolver)) return opaquePayloads.get(resolver);
+    const entry = classes.get(resolver.constructor);
+    if (!entry) throw new BagSerializationError(`Unregistered resolver: ${resolver.constructor.name}`);
+    const parameters = entry.encode(resolver);
+    const data = {
+        resolver_module: entry.module, resolver_class: entry.name,
+        args: parameters.args ?? [], kwargs: parameters.kwargs ?? {},
+    };
+    validateDescription(data);
+    validateJson(data);
+    return MARKER + JSON.stringify(data);
+}
+
+export function decodeResolver(value) {
+    if (typeof value !== 'string' || !value.startsWith(MARKER)) return null;
+    const payload = value.slice(MARKER.length);
+    // Preserve the exact signed token. Never trust its contents in the browser.
+    if (/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*\.[A-Za-z0-9_-]+$/.test(payload)) {
+        return new OpaqueResolver(value);
+    }
+    let data;
+    try { data = JSON.parse(payload); }
+    catch { throw new BagSerializationError('Invalid resolver JSON or signed token'); }
+    validateDescription(data);
+    const entry = registrations.get(JSON.stringify([data.resolver_module, data.resolver_class]));
+    if (!entry) return new OpaqueResolver(value);
+    const resolver = entry.decode({ args: data.args ?? [], kwargs: data.kwargs });
+    if (!(resolver instanceof entry.cls)) {
+        throw new BagSerializationError('Resolver decoder returned an incompatible instance');
+    }
+    return resolver;
+}
+
+export function encodeAttrs(attr) {
+    return Object.fromEntries(Object.entries(attr || {}).map(([key, value]) =>
+        [key, value instanceof BagResolver ? encodeResolver(value) : value]));
+}
+
+export function decodeAttrs(attr) {
+    return Object.fromEntries(Object.entries(attr || {}).map(([key, value]) =>
+        [key, decodeResolver(value) ?? value]));
+}