@senlinz/import-export 0.1.2 → 1.0.1

package/README.md

@@ -10,29 +10,14 @@ High-level browser API for Excel template generation, export, and import.
 pnpm add @senlinz/import-export
 ```
 
-## Choose your mode
+## WASM loading
 
-### Default mode (recommended)
-
-- No setup required.
-- `importExcel`, `importExcelDynamic`, `exportExcel`, `fromExcel`, `fromExcelDynamic`, `toExcel`, `downloadExcelTemplate`, and `generateExcelTemplate` automatically initialize the bundled WASM runtime.
-- Best for most browser applications.
-
-### Advanced mode
-
-- Call `initializeWasm(...)` yourself before using the Excel APIs.
-- Use this when you want custom WASM hosting, bundler control, or to reuse bytes/modules that you loaded elsewhere.
-- Supported manual inputs: `source`, `bytes`, or `module`.
-- `bundledWasmSource` is also exported for self-contained demos/tests that still want explicit manual initialization.
+- `importExcel`, `importExcelDynamic`, `exportExcel`, `fromExcel`, `fromExcelDynamic`, `toExcel`, `downloadExcelTemplate`, and `generateExcelTemplate` auto-load and initialize the bundled WASM asset on first use.
+- In Vite and other browser ESM bundlers, no manual `initializeWasm(...)` call or `?url` import is required when using the high-level core package.
+- If you need to manage the WASM module yourself, use `@senlinz/import-export-wasm` directly instead of this package.
 
 ```ts
-import { initializeWasm, toExcel } from '@senlinz/import-export';
-
-const wasmBytes = new Uint8Array(
-  await (await fetch('/assets/imexport_wasm_bg.wasm')).arrayBuffer()
-);
-
-initializeWasm({ bytes: wasmBytes });
+import { toExcel } from '@senlinz/import-export';
 
 const workbook = await toExcel({
   name: 'TomAndJerry',
@@ -40,8 +25,6 @@ const workbook = await toExcel({
 }, [{ name: 'Tom' }]);
 ```
 
-If you provide invalid manual input, `initializeWasm(...)` throws a clear error immediately.
-
 ## Supported API
 
 ### Stable definition fields
@@ -165,6 +148,27 @@ const rows = await importExcel(definition);
 - Grouped export objects must use `{ value?, children: [...] }` for configured `dataGroup` columns.
 - Image columns require `imageFetcher`.
 
+## Image fetcher with URL validation
+
+When using `imageFetcher` for image columns, validate URLs before fetching to avoid requests to untrusted origins. The example below enforces HTTPS and checks the HTTP response status:
+
+```typescript
+const imageFetcher = async (url: string): Promise<Uint8Array> => {
+  const parsed = new URL(url);
+  if (parsed.protocol !== 'https:') {
+    throw new Error(`Refusing to fetch image from non-HTTPS URL: ${url}`);
+  }
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch image: ${response.status} ${response.statusText}`);
+  }
+  const buffer = await response.arrayBuffer();
+  return new Uint8Array(buffer);
+};
+```
+
+For server-side contexts, also consider restricting URLs to trusted domains and rejecting private/internal network addresses. See [SECURITY.md](../../SECURITY.md) for the full image fetcher trust model and additional guidance.
+
 ## Advanced supported features
 
 These advanced features are supported and considered part of the public API:
@@ -183,17 +187,33 @@ These advanced features are supported and considered part of the public API:
 - `downloadExcelTemplate`, `exportExcel`, `importExcel`, and `importExcelDynamic` require DOM/browser APIs.
 - `fromExcel`, `toExcel`, and `generateExcelTemplate` can be used in other runtimes when browser-compatible globals are available.
 - `fromExcelDynamic` can also be used in other runtimes when browser-compatible globals are available.
-- `initializeWasm` can be used to pre-initialize the runtime with caller-managed `source`, `bytes`, or `module`.
+- The core package initializes its emitted bundled WASM asset asynchronously before the first workbook operation.
 
 ## Examples
 
 - [Basic browser example](./examples/basic-browser.html)
-- [Manual WASM browser example](./examples/manual-wasm-browser.html)
 - [Grouped export example](./examples/grouped-export.html)
 - [Definition validation example](./examples/definition-errors.html)
 
 These examples are covered by Playwright tests in [`./tests/import-export.spec.ts`](./tests/import-export.spec.ts).
 
+## Test utilities
+
+The package exposes a `testUtils` namespace for use in consumer test suites:
+
+```ts
+import { testUtils } from '@senlinz/import-export';
+```
+
+> **Warning:** `testUtils` is intended for testing purposes only. These helpers are internal implementation details and carry **no stability guarantee** — they may change or be removed in any release without notice.
+
+| Helper | Description |
+|---|---|
+| `normalizeDefinition(definition)` | Normalizes and validates an `ExcelDefinition`, trimming strings and applying defaults. |
+| `normalizeDynamicImportOptions(options?)` | Normalizes and validates dynamic import options (e.g. `headerRow`, `maxFileSizeBytes`). |
+| `sanitizeTextCellValue(value, escapeFormulas?)` | Sanitizes a text cell value to prevent formula injection. Prefixes formula-like values with a single quote when `escapeFormulas` is `true` (the default). |
+| `defaultMaxFileSizeBytes` | The default maximum file size in bytes (25 MB). |
+
 ## Known limitations
 
 - Parent headers and data groups must be declared before dependent columns.

package/README.zh.md

@@ -10,29 +10,14 @@
 pnpm add @senlinz/import-export
 ```
 
-## 选择使用模式
+## WASM 加载
 
-### 默认模式（推荐）
-
-- 无需额外初始化。
-- `importExcel`、`importExcelDynamic`、`exportExcel`、`fromExcel`、`fromExcelDynamic`、`toExcel`、`downloadExcelTemplate`、`generateExcelTemplate` 会自动初始化内置 WASM 运行时。
-- 适合绝大多数浏览器场景。
-
-### 高级模式
-
-- 在使用这些 Excel API 之前，先手动调用 `initializeWasm(...)`。
-- 适用于自定义 WASM 托管、需要自己控制 bundler 行为，或希望复用已加载 bytes / module 的场景。
-- 支持的手动输入：`source`、`bytes`、`module`。
-- 同时也导出了 `bundledWasmSource`，方便在自包含 demo / 测试中显式走手动初始化流程。
+- `importExcel`、`importExcelDynamic`、`exportExcel`、`fromExcel`、`fromExcelDynamic`、`toExcel`、`downloadExcelTemplate`、`generateExcelTemplate` 会在首次调用时自动加载并初始化内置 WASM 资源。
+- 在 Vite 和其他浏览器 ESM bundler 中，使用高阶 core 包时不再需要手动调用 `initializeWasm(...)` 或自己处理 `?url`。
+- 如果你需要自行管理 WASM 模块，请直接使用 `@senlinz/import-export-wasm`，而不是这个高阶包。
 
 ```ts
-import { initializeWasm, toExcel } from '@senlinz/import-export';
-
-const wasmBytes = new Uint8Array(
-  await (await fetch('/assets/imexport_wasm_bg.wasm')).arrayBuffer()
-);
-
-initializeWasm({ bytes: wasmBytes });
+import { toExcel } from '@senlinz/import-export';
 
 const workbook = await toExcel({
   name: 'TomAndJerry',
@@ -40,8 +25,6 @@ const workbook = await toExcel({
 }, [{ name: 'Tom' }]);
 ```
 
-如果手动传入的 WASM 输入无效，`initializeWasm(...)` 会立即抛出清晰的错误信息。
-
 ## 支持的 API
 
 ### 稳定的 definition 字段
@@ -175,12 +158,11 @@ const result = await fromExcelDynamic(fileBytes, {
 - 主要面向浏览器 ESM 运行时。
 - `downloadExcelTemplate`、`exportExcel`、`importExcel`、`importExcelDynamic` 依赖 DOM / 浏览器 API。
 - 当运行时提供兼容的浏览器全局对象时，也可以使用 `fromExcel`、`fromExcelDynamic`、`toExcel`、`generateExcelTemplate`。
-- `initializeWasm` 可用于使用调用方提供的 `source`、`bytes` 或 `module` 预初始化运行时。
+- core 包会在首次执行工作簿操作前，异步初始化构建产物中的内置 WASM 资源。
 
 ## 示例
 
 - [基础浏览器示例](./examples/basic-browser.html)
-- [手动初始化 WASM 的浏览器示例](./examples/manual-wasm-browser.html)
 - [分组导出示例](./examples/grouped-export.html)
 - [Definition 校验示例](./examples/definition-errors.html)