@senlinz/import-export-wasm 0.1.0-beta.8 → 0.1.0

package/LICENSE

@@ -1,33 +1,33 @@
-MIT License
-
-Copyright (c) 2024, senlinz
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
----
-
-This project includes third-party software licensed under the MIT License and the Apache License 2.0:
-
-## rust_xlsxwriter
-
-MIT License (MIT) or Apache License, Version 2.0
-
-## calamine
-
+MIT License
+
+Copyright (c) 2024, senlinz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This project includes third-party software licensed under the MIT License and the Apache License 2.0:
+
+## rust_xlsxwriter
+
+MIT License (MIT) or Apache License, Version 2.0
+
+## calamine
+
 MIT License

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.
-
-## 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/).
-
-## Usage
-Directly use WebAssembly in browser environments. 
-[Example](./tests/index.html)
+# @senlinz/import-export-wasm
+
+Direct Rust/WebAssembly bindings for importing, exporting, and templating Excel workbooks.
+
+[中文文档](./README.zh.md)
+
+## 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.8",
+  "version": "0.1.0",
   "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"
   }
 }