@genrojs/bag

中文文档
0.12.0发布于 2026/11/01Apache-2.0TypeScriptES Module构建来源已验证近 30 天下载 4479

JavaScript port of genro-bag - hierarchical data container

原始使用文档
文档目录13 节
  1. Status
  2. Overview
  3. Architecture
  4. Core Classes
  5. Installation
  6. Usage
  7. With Builder
  8. With Compiler
  9. Documentation
  10. Development
  11. License
  12. JSR distribution
  13. Optional developer HTML representation

genro-bag-js

Current release: 0.12.0. Resolver inputs are the declared parameters; read-time kwargs are a one-off read. See BREAKING_CHANGES.md.

0.11.0 — breaking API: read the ingestion and scheduling migration note before upgrading dependent projects.

TypeScript/JavaScript port of 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

ClassDescription
BagHierarchical container with labeled nodes
BagNodeIndividual node with value and attributes
BagBuilderBaseBase class for declarative structure builders
BagCompilerBaseBase class for output generators (DOM, HTML, etc.)
BagResolverLazy loading support

Installation

The same package is published on two registries:

# npm
npm install @genrojs/bag

# JSR
npx jsr add @genro/bag

From npm, import from @genrojs/bag; from JSR, import from @genro/bag.

Usage

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

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

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

Development

# Install dependencies
pnpm install

# Run tests
pnpm test

# Build
pnpm build

# Type check
pnpm typecheck

License

Apache License 2.0 - see 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

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.

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.

版本与发布记录

@genrojs/bag 共发布 7 个版本,首次发布于 2026/10/01;过去 12 个月发布了 7 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.12.0latest2026/11/0114 天前
0.11.12026/10/2819 天前
0.11.02026/10/151 个月前
0.10.32026/10/041 个月前
0.10.22026/10/041 个月前
0.10.12026/10/011 个月前

关于 @genrojs/bag 的常见问题

@genrojs/bag 是什么?

JavaScript port of genro-bag - hierarchical data container

如何安装 @genrojs/bag?

在项目目录运行 npm install @genrojs/bag,或使用 pnpm add / yarn add / bun add。

@genrojs/bag 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@genrojs/bag 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@genrojs/bag 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@genrojs/bag 可以商用吗?

@genrojs/bag 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@genrojs/bag 的下载量有多少?

根据 npm 官方下载统计,@genrojs/bag 在 2026/10/16 – 2026/11/14 这 30 天内被下载 4,479 次,日均约 149 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@genrojs/bag 还在维护吗?

最新版本 0.12.0 发布于 2026/11/01(14 天前);至今共发布 7 个版本,其中过去 12 个月发布了 7 个;首次发布于 2026/10/01。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。