@senlinz/import-export-wasm 0.1.0-beta.23 → 0.1.0-beta.24

package/README.md

@@ -1,13 +1,87 @@
 # @senlinz/import-export-wasm
-**@senlinz/import-export-wasm** is the Rust WebAssembly core library for the **@senlinz/import-export** library. It provides the core logic for handling Excel data in browser environments.
 
-> **Note:** This library is currently in beta. Features and APIs may change.
+Direct Rust/WebAssembly bindings for importing, exporting, and templating Excel workbooks.
 
-## Features
-- Rust WebAssembly core for efficient Excel data handling.
-- Read using [calamine](https://docs.rs/calamine/).
-- Write using [rust_xlsxwriter](https://docs.rs/rust_xlsxwriter/).
+[中文文档](./README.zh.md)
 
-## Usage
-Directly use WebAssembly in browser environments. 
-[Example](./tests/index.html)
+## Install
+
+```bash
+pnpm add @senlinz/import-export-wasm
+```
+
+## Initialization
+
+Build the package and load the generated module in the browser:
+
+```ts
+import init, {
+  createTemplate,
+  exportData,
+  importData,
+  ExcelInfo,
+  ExcelColumnInfo,
+  ExcelData,
+  ExcelRowData,
+  ExcelColumnData,
+} from '@senlinz/import-export-wasm';
+
+await init();
+```
+
+## Direct WASM usage
+
+```ts
+const info = new ExcelInfo(
+  'TomAndJerry',
+  'sheet1',
+  [
+    new ExcelColumnInfo('name', 'Name'),
+    new ExcelColumnInfo('age', 'Age').withDataType('number'),
+    new ExcelColumnInfo('category', 'Category').withAllowedValues(['Cat', 'Mouse']),
+  ],
+  'senlinz',
+  '2024-11-01T08:00:00',
+);
+
+const template = createTemplate(info);
+
+const data = new ExcelData([
+  new ExcelRowData([
+    new ExcelColumnData('name', 'Tom'),
+    new ExcelColumnData('age', '12'),
+    new ExcelColumnData('category', 'Cat'),
+  ]),
+]);
+
+const workbook = await exportData(info, data);
+const imported = importData(info, workbook);
+```
+
+## Supported schema rules
+
+- Column keys must be unique.
+- Header names must be non-empty.
+- Supported `dataType` values are `text`, `number`, `date`, and `image`.
+- Parent columns must be declared before child columns.
+- `dataGroupParent` values must refer to a previously declared `dataGroup`.
+
+## Direct WASM examples
+
+- [Browser example](./examples/direct-browser.html)
+
+The browser example is covered by Playwright tests in [`./tests/wasm.test.js`](./tests/wasm.test.js).
+
+## Runtime notes
+
+- Browser usage requires the generated JS/WASM assets from `wasm-pack build`.
+- Image export requires `.withImageFetcher(...)`.
+- Invalid schemas and invalid exported number/date values now fail with explicit errors.
+
+## Development
+
+```bash
+cargo test --lib
+wasm-pack build --release --target web
+pnpm e2e-test
+```

package/README.zh.md

@@ -0,0 +1,87 @@
+# @senlinz/import-export-wasm
+
+用于导入、导出和生成 Excel 工作簿的 Rust / WebAssembly 直接绑定。
+
+[English](./README.md)
+
+## 安装
+
+```bash
+pnpm add @senlinz/import-export-wasm
+```
+
+## 初始化
+
+先构建包，再在浏览器中加载生成的模块：
+
+```ts
+import init, {
+  createTemplate,
+  exportData,
+  importData,
+  ExcelInfo,
+  ExcelColumnInfo,
+  ExcelData,
+  ExcelRowData,
+  ExcelColumnData,
+} from '@senlinz/import-export-wasm';
+
+await init();
+```
+
+## 直接使用 WASM
+
+```ts
+const info = new ExcelInfo(
+  'TomAndJerry',
+  'sheet1',
+  [
+    new ExcelColumnInfo('name', 'Name'),
+    new ExcelColumnInfo('age', 'Age').withDataType('number'),
+    new ExcelColumnInfo('category', 'Category').withAllowedValues(['Cat', 'Mouse']),
+  ],
+  'senlinz',
+  '2024-11-01T08:00:00',
+);
+
+const template = createTemplate(info);
+
+const data = new ExcelData([
+  new ExcelRowData([
+    new ExcelColumnData('name', 'Tom'),
+    new ExcelColumnData('age', '12'),
+    new ExcelColumnData('category', 'Cat'),
+  ]),
+]);
+
+const workbook = await exportData(info, data);
+const imported = importData(info, workbook);
+```
+
+## 支持的 Schema 规则
+
+- 列 key 必须唯一。
+- 表头名称不能为空。
+- `dataType` 仅支持 `text`、`number`、`date`、`image`。
+- 父级列必须先于子级列声明。
+- `dataGroupParent` 必须引用已声明的 `dataGroup`。
+
+## 直接 WASM 示例
+
+- [浏览器示例](./examples/direct-browser.html)
+
+该浏览器示例由 [`./tests/wasm.test.js`](./tests/wasm.test.js) 中的 Playwright 用例覆盖。
+
+## 运行时说明
+
+- 浏览器使用前需要通过 `wasm-pack build` 生成 JS / WASM 产物。
+- 图片导出需要 `.withImageFetcher(...)`。
+- 非法 schema、非法数字值、非法日期值都会返回明确错误。
+
+## 开发
+
+```bash
+cargo test --lib
+wasm-pack build --release --target web
+pnpm e2e-test
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@senlinz/import-export-wasm",
-  "version": "0.1.0-beta.23",
+  "version": "0.1.0-beta.24",
   "description": "Rust WebAssembly for import/export excel files",
   "main": "pkg/imexport_wasm.js",
   "types": "pkg/imexport_wasm.d.ts",
@@ -9,7 +9,8 @@
     "pkg/imexport_wasm.bg.wasm.d.ts",
     "pkg/imexport_wasm.js",
     "pkg/imexport_wasm.d.ts",
-    "README.md"
+    "README.md",
+    "README.zh.md"
   ],
   "author": "senlin",
   "license": "MIT",
@@ -34,7 +35,7 @@
     "build": "wasm-pack build --release --target web",
     "publish-dry-run": "pnpm publish --dry-run --no-git-checks",
     "cargo-test": "cargo test --lib",
-    "e2e-serve": "wasm-pack build --release --target web -d tests/dist && serve -l 8080 ./tests",
+    "e2e-serve": "wasm-pack build --release --target web -d tests/dist && serve -l 8080 .",
     "e2e-test": "playwright test"
   }
 }

package/pkg/imexport_wasm.d.ts

@@ -246,6 +246,10 @@ export interface InitOutput {
     readonly excelinfo_withTitle: (a: number, b: number, c: number) => number;
     readonly excelinfo_withTitleFormat: (a: number, b: number) => number;
     readonly excelinfo_withTitleHeight: (a: number, b: number) => number;
+    readonly __wbg_excelrowdata_free: (a: number, b: number) => void;
+    readonly __wbg_get_excelrowdata_columns: (a: number) => [number, number];
+    readonly __wbg_set_excelrowdata_columns: (a: number, b: number, c: number) => void;
+    readonly excelrowdata_new: (a: number, b: number) => number;
     readonly __wbg_excelcolumndata_free: (a: number, b: number) => void;
     readonly __wbg_get_excelcolumndata_children: (a: number) => [number, number];
     readonly __wbg_get_excelcolumndata_key: (a: number) => [number, number];
@@ -257,10 +261,6 @@ export interface InitOutput {
     readonly excelcolumndata_newGroup: (a: number, b: number, c: number, d: number, e: number, f: number) => number;
     readonly excelcolumndata_newRootGroup: (a: number, b: number, c: number, d: number) => number;
     readonly excelcolumndata_withChildren: (a: number, b: number, c: number) => number;
-    readonly __wbg_excelrowdata_free: (a: number, b: number) => void;
-    readonly __wbg_get_excelrowdata_columns: (a: number) => [number, number];
-    readonly __wbg_set_excelrowdata_columns: (a: number, b: number, c: number) => void;
-    readonly excelrowdata_new: (a: number, b: number) => number;
     readonly __wbg_exceldata_free: (a: number, b: number) => void;
     readonly __wbg_get_exceldata_rows: (a: number) => [number, number];
     readonly __wbg_set_exceldata_rows: (a: number, b: number, c: number) => void;

package/pkg/imexport_wasm.js

@@ -1570,7 +1570,7 @@ function __wbg_get_imports() {
             return ret;
         },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { dtor_idx: 223, function: Function { arguments: [Externref], shim_idx: 377, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { dtor_idx: 227, function: Function { arguments: [Externref], shim_idx: 381, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm.wasm_bindgen__closure__destroy__h1014a67ffc8653bf, wasm_bindgen__convert__closures_____invoke__h70bb320d972e2f25);
             return ret;
         },