@genrojs/bag 0.10.1

package/LICENSE

@@ -0,0 +1,176 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/NOTICE

@@ -0,0 +1,7 @@
+genro-bag-js
+Copyright 2025 Softwell S.r.l.
+
+This product includes software developed at Softwell S.r.l.
+(https://www.softwell.it/).
+
+Licensed under the Apache License, Version 2.0.

package/README.md

@@ -0,0 +1,191 @@
+# genro-bag-js
+
+TypeScript/JavaScript port of [genro-bag](https://github.com/nicofirst1/genro-bag) - hierarchical data container with XML serialization, Builder pattern, and Compiler system.
+
+## Status
+
+**Development Status**: Pre-Alpha (documentation and planning)
+
+## Overview
+
+genro-bag-js brings the Python genro-bag architecture to JavaScript/TypeScript for:
+
+- **Browser**: DOM manipulation, UI frameworks, reactive updates
+- **Node.js**: Server-side processing, CLI tools
+- **Interoperability**: Same XML/JSON format as Python version
+- **Modern runtimes**: Deno, Bun support
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         SERVER (Python)                         │
+│                                                                 │
+│   Builder Python → creates "recipe" (structured Bag)           │
+│   bag.to_xml() → serializes for transport                      │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼  (HTTP / WebSocket)
+┌─────────────────────────────────────────────────────────────────┐
+│                        BROWSER (JavaScript)                     │
+│                                                                 │
+│   Bag.fromXml() → reconstructs structure                       │
+│   Expander → expands macros/components (optional)              │
+│   DOMCompiler → builds DOM/widgets dynamically                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Core Classes
+
+| Class | Description |
+|-------|-------------|
+| `Bag` | Hierarchical container with labeled nodes |
+| `BagNode` | Individual node with value and attributes |
+| `BagBuilderBase` | Base class for declarative structure builders |
+| `BagCompilerBase` | Base class for output generators (DOM, HTML, etc.) |
+| `BagResolver` | Lazy loading support |
+
+## Installation
+
+The same package is published on two registries:
+
+```bash
+# npm
+npm install @genrojs/bag
+
+# JSR
+npx jsr add @genro/bag
+```
+
+From npm, import from `@genrojs/bag`; from JSR, import from `@genro/bag`.
+
+## Usage
+
+```typescript
+import { Bag } from '@genrojs/bag';
+
+// Create a Bag
+const bag = new Bag();
+bag.set('config.name', 'My App');
+bag.set('config.version', '1.0.0');
+
+// Serialize
+const xml = bag.toXml();
+const json = bag.toJson();
+
+// Parse
+const restored = Bag.fromXml(xml);
+```
+
+### With Builder
+
+```typescript
+import { Bag, BagBuilderBase, element } from '@genrojs/bag';
+
+class GUIBuilder extends BagBuilderBase {
+  @element({ subTags: 'button,textfield' })
+  panel(title: string) {}
+
+  @element({ subTags: '' })
+  button(label: string, action?: string) {}
+}
+
+const gui = new Bag({ builder: GUIBuilder });
+const panel = gui.panel('Settings');
+panel.button('Save', 'doSave');
+panel.button('Cancel', 'doCancel');
+```
+
+### With Compiler
+
+```typescript
+import { BagCompilerBase, compiler } from '@genrojs/bag';
+
+class DOMCompiler extends BagCompilerBase {
+  @compiler
+  panel(node, children): HTMLElement {
+    const div = document.createElement('div');
+    div.className = 'panel';
+    children.forEach(child => div.appendChild(child));
+    return div;
+  }
+
+  @compiler
+  button(node, children): HTMLElement {
+    const btn = document.createElement('button');
+    btn.textContent = node.attr.label;
+    btn.onclick = () => this.handleAction(node.attr.action);
+    return btn;
+  }
+}
+```
+
+## Documentation
+
+- [Python alignment and TYTX compatibility](docs/python-alignment.md)
+
+- [Architecture Analysis](docs/analysis/analisi_bag_js_builder_js.md) - Detailed analysis of existing JS implementation
+- [Plan](docs/plan.md) - Implementation roadmap
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run tests
+pnpm test
+
+# Build
+pnpm build
+
+# Type check
+pnpm typecheck
+```
+
+## License
+
+Apache License 2.0 - see [LICENSE](LICENSE) for details.
+
+Copyright 2025 Softwell S.r.l.
+
+
+## JSR distribution
+
+The JavaScript package is published as `@genro/bag` on JSR. Use
+`bunx jsr add @genro/bag` or `npx jsr add @genro/bag`.
+Node.js 22+, Bun and modern browsers with Web Crypto are the supported targets.
+TYTX is resolved from JSR; no GitHub package checkout is needed.
+
+[![JSR](https://jsr.io/badges/@genro/bag)](https://jsr.io/@genro/bag)
+
+Deno publication keeps a 24-hour cooldown for external dependencies and exempts
+Genro JSR packages (`jsr:@genro/*` and their `npm:@jsr/genro__*` compatibility
+names). Releases are published only to JSR; the npm form downloads from
+`npm.jsr.io`, not npmjs.com. Verify each published dependency before adopting it.
+
+### Optional developer HTML representation
+
+The experimental inspector is a separate entry point, excluded from the main
+module and browser bundle. It may be removed in a future release.
+
+```js
+import { htmlRepr } from '@genrojs/bag/devtools';
+// With a bundler that supports CSS imports:
+import '@genrojs/bag/devtools/html-repr.css';
+
+const html = htmlRepr(bag, {title: 'Inspect Bag', showTypes: true});
+```
+
+Load the stylesheet separately when not using a CSS-aware bundler. The function
+returns an escaped HTML fragment; rendering it requires no additional script.
+Bag panels and attributes start collapsed. Options `openDepth` (default 0),
+`openAttributes` (default false), `showTypes` (default true), and `className`
+control presentation. The renderer reads static values without invoking
+resolvers. An optional `resolverParameters(resolver)` hook supplies additional
+metadata, including named callbacks; the hook must not execute the resolver.
+Resolver badges use the constructor name, which minification may change.
+
+All nodes are emitted even when collapsed: this is a static developer inspector,
+not a virtualized viewer for large datasets. Ancestor cycles are marked without
+mutating the Bag. The inspector is deliberately not installed on `Bag.prototype`.

package/docs/python-alignment.md

@@ -0,0 +1,156 @@
+# Python/JavaScript alignment
+
+Implemented against genro-bag Python 0.22.0. The runtime differences remain
+intentional: callbacks may return values or Promises, Web Storage replaces
+process environment variables, and there is no DataChangeCollector.
+
+## Release dependency
+
+Bag JS 0.4.0 uses the published TYTX `v0.15.0` Git tag over HTTPS. The lockfile
+pins its commit; no sibling checkout is required. TYTX exposes the public
+`getRegisteredType(suffix)` API and supports the Node 18 runtime declared by
+this package. Install with `npm ci` for development. `UuidResolver` selects
+Node crypto or browser Web Crypto through a conditional import; its API
+remains synchronous on both runtimes.
+
+## Registered Bag classes
+
+```js
+import { Bag } from '@genrojs/bag';
+import { registerClass } from '@genrojs/tytx';
+
+class SourceBag extends Bag {
+    static tytxSuffix = 'SOURCE';
+}
+registerClass(SourceBag);
+```
+
+Python registers its counterpart with `__tytx_suffix__ = 'SOURCE'`. Each
+runtime constructs its own class. Bag itself owns `X`; a registered subclass
+must own a distinct suffix. Registration uses exact constructors.
+
+`SourceBag.fromTytx(data)` reconstructs a SourceBag root and retains mixed
+branch types. JSON and MessagePack support normal and compact Bag rows.
+Bags also travel inside ordinary TYTX objects and arrays. Legacy subclasses
+that inherit `X` retain the Python root-class factory behavior for `X` branches.
+
+Unknown or missing parents throw `BagSerializationError` instead of moving
+children to the root. An unknown empty marker without descendants can still
+be indistinguishable from ordinary text. MessagePack scalar strings are not
+indiscriminately decoded as structural markers.
+
+## Tags and attribute queries
+
+`update(otherBag)` copies `nodeTag` and `xmlTag` on inserted nodes. On collisions,
+non-null incoming tags win; null tags retain the destination metadata. This
+also applies to recursive merges. JSON and TYTX round-trips retain `nodeTag`.
+
+`getItem('node?')` returns all attributes as an object. `node?a` returns one
+attribute, and `node?a&b` returns an array in the requested order. Attribute
+resolvers are resolved using their own parameters, without passing attributes
+from the containing node. A query returns immediately if all values are
+synchronous; otherwise it returns a Promise of the complete result. Rejected
+resolver Promises reject the query. Static reads return resolver objects intact.
+
+## Resolver descriptions
+
+TYTX, JSON and XML carry Python's `::RSLV:` descriptions. JSON node objects
+use `resolver`; XML uses `_resolver`. Resolver-valued attributes use the same
+marker. Reading a format does not call `load()`. Resolver caches are not
+serialized as independent data branches.
+
+Register JS counterparts explicitly, with adapters for argument naming and
+runtime differences. The module and name identify a wire type; they never
+cause dynamic imports or code evaluation.
+
+```js
+import { BagResolver, registerResolver } from '@genrojs/bag';
+
+class NumberResolver extends BagResolver {
+    load(options) { return options.number; }
+}
+registerResolver(NumberResolver, {
+    module: 'myapp.resolvers',
+    name: 'NumberResolver',
+    encode: resolver => ({ kwargs: { number: resolver._kw.number } }),
+    decode: ({ kwargs }) => new NumberResolver({ number: kwargs.number }),
+});
+```
+
+Adapters must construct inert resolvers. `encode` returns JSON-compatible
+`args` and `kwargs`; callbacks and non-JSON parameter objects cannot travel.
+Unregistered JS resolver instances fail explicitly when serialized.
+
+Unknown descriptions become `OpaqueResolver` instances. Their read-only
+`payload` preserves the exact received marker, including whitespace and
+signatures. Attempting to resolve them locally throws. Signed tokens remain
+opaque even if their class has a JS counterpart: the browser has no signing
+key and does not authenticate them. They travel unchanged back to the server,
+which verifies signature and expiry. Remote execution is outside this API.
+
+The existing XML API emits fragments; wrap them in `<GenRoBag>...</GenRoBag>`
+for a round-trip with Python (which recognizes that wrapper). JS `fromXml`
+reads the children of the document element.
+
+## Web Storage conversion
+
+```js
+new StorageResolver({
+    key: 'preferences.zoom', storageType: 'local', dtype: 'L', defaultValue: '100',
+});
+```
+
+The existing `storageType: 'local' | 'session'` selects the backend. `dtype`
+optionally converts the string or non-null default through TYTX. With no dtype,
+values retain the original behavior; null defaults remain null. Invalid numeric
+strings throw instead of returning a partially parsed number. No separate
+LocalStorageResolver, SessionStorageResolver or EnvResolver is introduced.
+
+## Verification
+
+- `npm test`: existing JS tests and new alignment contracts.
+- `node --test js/test/test_registry.js js/test/test_registry_lookup.js` in TYTX.
+- `python -m pytest tests/cross-lang`: requires Python 3.11+, pytest, msgpack,
+  and the current Python genro-bag, genro-tytx and genro-toolbox packages.
+  The alignment bridge checks mixed branch identities inside JS and Python,
+  resolver counterparts, and signed payloads verified on return to Python.
+
+## Legacy JavaScript digest calls
+
+The signature remains `digest(what, condition, asColumns)`. For compatibility
+with legacy JavaScript callers, a boolean second argument is interpreted as
+`asColumns`, with no filter, and emits a `console.warn` deprecation notice.
+Migrate `digest(what, true)` to `digest(what, null, true)` (and likewise for
+`false`). Callable filters retain their existing behavior and do not warn.
+The `columns()` helper already uses the explicit three-argument form.
+
+## JavaScript items contract
+
+`Bag.items()` returns an ordered array of `{key, value}` objects, matching
+legacy JavaScript Bag. Values are resolved through `getValue()` and nested
+Bags retain their identity. This differs from Python's key/value pairs.
+
+## JavaScript update contract
+
+`update(source, mode, reason, ignoreNone=false)` retains the legacy JavaScript
+positional contract. With `mode='static'`, incoming resolvers are preserved and
+not executed, including newly inserted nodes. Otherwise their results are
+copied; an incoming resolved result replaces a destination resolver. Nested
+Bags merge recursively unless the incoming `__replace` marker requests
+replacement. The marker is consumed and `reason` is propagated to events.
+Null values overwrite existing values by default. The previous standalone
+`ignoreNone` extension is now explicitly the fourth argument, not the mode.
+This JS signature intentionally differs from Python's `resolved` flag.
+
+Unlike the historical implementation, insertion does not drop static resolvers.
+This repairs the lazy-copy contract instead of retaining that historical bug.
+
+## Constructor null attributes
+
+`BagNode` accepts `removeNullAttributes` as its eighth constructor argument,
+matching Python's `_remove_null_attributes` position and default (`true`).
+Default construction removes null attributes; passing `false` preserves them.
+Zero, false and empty strings are preserved in either mode. `Bag.setItem`
+forwards its existing null-removal option when constructing a new node as well
+as when updating one. This is an optional argument and a propagation bug fix,
+not a new default policy. See `constructor-null-attributes.test.js`.

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@genrojs/bag",
+  "version": "0.10.1",
+  "description": "JavaScript port of genro-bag - hierarchical data container",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./devtools": "./src/devtools/index.js",
+    "./devtools/html-repr.css": "./src/devtools/html-repr.css"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "docs/python-alignment.md"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.js",
+    "test:coverage": "c8 --reporter=lcov --reporter=text node --test tests/*.test.js"
+  },
+  "keywords": [
+    "bag",
+    "hierarchical",
+    "xml",
+    "builder",
+    "genro"
+  ],
+  "author": "Genropy Team",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/genro-org/genro-bag-js.git"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@genrojs/tytx": "^0.16.1",
+    "@msgpack/msgpack": "^3.1.3",
+    "@xmldom/xmldom": "^0.9.12",
+    "big.js": "^7.0.1"
+  },
+  "devDependencies": {
+    "c8": "^10.1.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}