md-spreadsheet-parser 1.0.0

package/README.md

@@ -0,0 +1,158 @@
+# md-spreadsheet-parser (NPM)
+
+<p align="center">
+  <img src="https://img.shields.io/badge/wasm-powered-purple.svg" alt="WASM Powered" />
+  <a href="https://github.com/f-y/md-spreadsheet-parser/blob/main/LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License" />
+  </a>
+</p>
+
+**md-spreadsheet-parser** is a robust, zero-dependency Markdown table parser and manipulator for Node.js.
+It is powered by the [Python Core](https://github.com/f-y/md-spreadsheet-parser) compiled to WebAssembly, ensuring 100% logic parity with the Python version while running natively in Node.js.
+
+## Features
+
+- **🚀 High Performance**: Pre-compiled WASM binary (initialized in ~160ms).
+- **💪 Robust Parsing**: Handles GFM tables, missing columns, and escaped pipes correctly.
+- **🛠️ Spreadsheet Operations**: Edit cells, add/remove rows, and re-generate Markdown programmatically.
+- **🛡️ Type-Safe Validation**: Validate table data against schemas (Plain Object or Zod).
+- **📂 File System Support**: Direct file reading capabilities.
+
+## Installation
+
+```bash
+npm install md-spreadsheet-parser
+```
+
+## Usage Guide
+
+### 1. Basic Parsing (String)
+
+Parse a Markdown table string into a structured `Table` object.
+
+```javascript
+import { parseTable } from 'md-spreadsheet-parser';
+
+const markdown = `
+| Name | Age |
+| --- | --- |
+| Alice | 30 |
+`;
+
+const table = parseTable(markdown);
+console.log(table.rows); // [ [ 'Alice', '30' ] ]
+```
+
+### 2. File System Usage
+
+You can parse files directly without reading them into a string first.
+
+```javascript
+import { parseWorkbookFromFile, scanTablesFromFile } from 'md-spreadsheet-parser';
+
+// Parse entire workbook (multiple sheets)
+const workbook = parseWorkbookFromFile('./data.md');
+console.log(`Parsed ${workbook.sheets.length} sheets`);
+
+// Validating contents using Lookup API
+const sheet = workbook.getSheet('Sheet1');
+if (sheet) {
+    const table = sheet.getTable(0); // Get first table
+    console.log(table.headers);
+}
+
+// Or just scan for all tables in a file
+const tables = scanTablesFromFile('./readme.md');
+console.log(`Found ${tables.length} tables`);
+```
+
+### 3. Programmatic Editing
+
+Table objects are mutable (CoW-like behavior internally). You can modify them and export back to Markdown.
+
+```javascript
+import { parseTable } from 'md-spreadsheet-parser';
+
+const table = parseTable("| Item | Price |\n|---|---|\n| Apple | 100 |");
+
+// Update Cell (Row 0, Col 1)
+table.updateCell(0, 1, "150");
+
+// Convert back to Markdown
+console.log(table.toMarkdown());
+// | Item | Price |
+// | --- | --- |
+// | Apple | 150 |
+```
+
+### 4. Type-Safe Validation (toModels)
+
+You can convert string-based table data into typed objects.
+
+#### Basic Usage (Plain Object Schema)
+You can provide a simple schema object with converter functions.
+
+```javascript
+const markdown = `
+| id | active |
+| -- | ------ |
+| 1  | yes    |
+`;
+const table = parseTable(markdown);
+
+// Define Schema
+const UserSchema = {
+    id: (val) => Number(val),
+    active: (val) => val === 'yes'
+};
+
+const users = table.toModels(UserSchema);
+console.log(users);
+// [ { id: 1, active: true } ]
+```
+
+#### Advanced Usage (Zod)
+For robust validation, use [Zod](https://zod.dev/).
+
+```javascript
+import { z } from 'zod';
+
+const UserZodSchema = z.object({
+    id: z.coerce.number(),
+    active: z.string().transform(v => v === 'yes')
+});
+
+const users = table.toModels(UserZodSchema);
+// [ { id: 1, active: true } ]
+```
+
+## API Documentation
+
+Since this package is a direct wrapper around the Python core, the fundamental concepts are identical. The API naming conventions are adapted for JavaScript (camelCase instead of snake_case).
+
+- **Core Documentation**: [Python User Guide](https://github.com/f-y/md-spreadsheet-parser#usage)
+- **Cookbook**: [Common Recipes](https://github.com/f-y/md-spreadsheet-parser/blob/main/COOKBOOK.md)
+
+### Key Function Mappings
+
+| Python (Core) | JavaScript (NPM) | Description |
+|---|---|---|
+| `parse_table(md)` | `parseTable(md)` | Parse a single table string |
+| `parse_workbook(md)` | `parseWorkbook(md)` | Parse entire workbook string |
+| `scan_tables(md)` | `scanTables(md)` | Extract all tables from string |
+| `parse_workbook_from_file(path)` | `parseWorkbookFromFile(path)` | Parse file to Workbook |
+| `scan_tables_from_file(path)` | `scanTablesFromFile(path)` | Extract tables from file |
+| `Table.to_markdown()` | `Table.toMarkdown()` | Generate Markdown |
+| `Table.update_cell(r, c, v)` | `Table.updateCell(r, c, v)` | Update specific cell |
+| `Table.to_models(schema)` | `Table.toModels(schema)` | Convert to typed objects |
+| `Workbook.get_sheet(name)` | `Workbook.getSheet(name)` | Get sheet by name |
+| `Sheet.get_table(index)` | `Sheet.getTable(index)` | Get table by index |
+
+## Architecture
+
+This package uses `componentize-py` to bundle the Python library as a WASM Component.
+For more details, see [ARCHITECTURE.md](./ARCHITECTURE.md).
+
+## License
+
+MIT

package/dist/interfaces/example-spreadsheet-types.d.ts

@@ -0,0 +1,50 @@
+/** @module Interface example:spreadsheet/types **/
+export type AlignmentType = string;
+export interface ConversionSchema {
+  booleanPairs?: string,
+  customConverters?: string,
+  fieldConverters?: string,
+}
+export interface ExcelParsingSchema {
+  headerRows?: number,
+  fillMergedHeaders?: boolean,
+  delimiter?: string,
+  headerSeparator?: string,
+}
+export interface MultiTableParsingSchema {
+  columnSeparator?: string,
+  headerSeparatorChar?: string,
+  requireOuterPipes?: boolean,
+  stripWhitespace?: boolean,
+  convertBrToNewline?: boolean,
+  rootMarker?: string,
+  sheetHeaderLevel?: number,
+  tableHeaderLevel?: number,
+  captureDescription?: boolean,
+}
+export interface ParsingSchema {
+  columnSeparator?: string,
+  headerSeparatorChar?: string,
+  requireOuterPipes?: boolean,
+  stripWhitespace?: boolean,
+  convertBrToNewline?: boolean,
+}
+export interface Table {
+  headers?: Array<string>,
+  rows: Array<Array<string>>,
+  alignments?: Array<AlignmentType>,
+  name?: string,
+  description?: string,
+  metadata?: string,
+  startLine?: number,
+  endLine?: number,
+}
+export interface Sheet {
+  name: string,
+  tables: Array<Table>,
+  metadata?: string,
+}
+export interface Workbook {
+  sheets: Array<Sheet>,
+  metadata?: string,
+}

package/dist/interfaces/exports.d.ts

@@ -0,0 +1,100 @@
+/** @module Interface exports **/
+export function init(appName: string, symbols: Symbols, stubWasi: boolean): void;
+export interface Function {
+  protocol: string,
+  name: string,
+}
+export interface Constructor {
+  module: string,
+  protocol: string,
+}
+export interface Static {
+  module: string,
+  protocol: string,
+  name: string,
+}
+export type FunctionExportKind = FunctionExportKindFreestanding | FunctionExportKindConstructor | FunctionExportKindMethod | FunctionExportKindStatic;
+export interface FunctionExportKindFreestanding {
+  tag: 'freestanding',
+  val: Function,
+}
+export interface FunctionExportKindConstructor {
+  tag: 'constructor',
+  val: Constructor,
+}
+export interface FunctionExportKindMethod {
+  tag: 'method',
+  val: string,
+}
+export interface FunctionExportKindStatic {
+  tag: 'static',
+  val: Static,
+}
+export type ReturnStyle = ReturnStyleNone | ReturnStyleNormal | ReturnStyleResult;
+export interface ReturnStyleNone {
+  tag: 'none',
+}
+export interface ReturnStyleNormal {
+  tag: 'normal',
+}
+export interface ReturnStyleResult {
+  tag: 'result',
+}
+export interface FunctionExport {
+  kind: FunctionExportKind,
+  returnStyle: ReturnStyle,
+}
+export interface Resource {
+  'package': string,
+  name: string,
+}
+export interface Record {
+  'package': string,
+  name: string,
+  fields: Array<string>,
+}
+export interface Flags {
+  'package': string,
+  name: string,
+  u32Count: number,
+}
+export interface Tuple {
+  count: number,
+}
+export interface Case {
+  name: string,
+  hasPayload: boolean,
+}
+export interface Variant {
+  'package': string,
+  name: string,
+  cases: Array<Case>,
+}
+export interface Enum {
+  'package': string,
+  name: string,
+  count: number,
+}
+/**
+ * # Variants
+ * 
+ * ## `"non-nesting"`
+ * 
+ * ## `"nesting"`
+ */
+export type OptionKind = 'non-nesting' | 'nesting';
+export interface ResultRecord {
+  hasOk: boolean,
+  hasErr: boolean,
+}
+export interface Symbols {
+  exports: Array<FunctionExport>,
+  resources: Array<Resource>,
+  records: Array<Record>,
+  flags: Array<Flags>,
+  tuples: Array<Tuple>,
+  variants: Array<Variant>,
+  enums: Array<Enum>,
+  options: Array<OptionKind>,
+  results: Array<ResultRecord>,
+}

package/dist/interfaces/wasi-cli-environment.d.ts

@@ -0,0 +1,4 @@
+/** @module Interface wasi:cli/environment@0.2.0 **/
+export function getEnvironment(): Array<[string, string]>;
+export function getArguments(): Array<string>;
+export function initialCwd(): string | undefined;

package/dist/interfaces/wasi-cli-exit.d.ts

@@ -0,0 +1,3 @@
+/** @module Interface wasi:cli/exit@0.2.0 **/
+export function exit(status: Result<void, void>): void;
+export type Result<T, E> = { tag: 'ok', val: T } | { tag: 'err', val: E };

package/dist/interfaces/wasi-cli-stderr.d.ts

@@ -0,0 +1,3 @@
+/** @module Interface wasi:cli/stderr@0.2.0 **/
+export function getStderr(): OutputStream;
+export type OutputStream = import('./wasi-io-streams.js').OutputStream;

package/dist/interfaces/wasi-cli-stdin.d.ts

@@ -0,0 +1,3 @@
+/** @module Interface wasi:cli/stdin@0.2.0 **/
+export function getStdin(): InputStream;
+export type InputStream = import('./wasi-io-streams.js').InputStream;

package/dist/interfaces/wasi-cli-stdout.d.ts

@@ -0,0 +1,3 @@
+/** @module Interface wasi:cli/stdout@0.2.0 **/
+export function getStdout(): OutputStream;
+export type OutputStream = import('./wasi-io-streams.js').OutputStream;

package/dist/interfaces/wasi-cli-terminal-input.d.ts

@@ -0,0 +1,8 @@
+/** @module Interface wasi:cli/terminal-input@0.2.0 **/
+
+export class TerminalInput {
+  /**
+   * This type does not have a public constructor.
+   */
+  private constructor();
+}

package/dist/interfaces/wasi-cli-terminal-output.d.ts

@@ -0,0 +1,8 @@
+/** @module Interface wasi:cli/terminal-output@0.2.0 **/
+
+export class TerminalOutput {
+  /**
+   * This type does not have a public constructor.
+   */
+  private constructor();
+}

package/dist/interfaces/wasi-cli-terminal-stderr.d.ts

@@ -0,0 +1,3 @@
+/** @module Interface wasi:cli/terminal-stderr@0.2.0 **/
+export function getTerminalStderr(): TerminalOutput | undefined;
+export type TerminalOutput = import('./wasi-cli-terminal-output.js').TerminalOutput;

package/dist/interfaces/wasi-cli-terminal-stdin.d.ts

@@ -0,0 +1,3 @@
+/** @module Interface wasi:cli/terminal-stdin@0.2.0 **/
+export function getTerminalStdin(): TerminalInput | undefined;
+export type TerminalInput = import('./wasi-cli-terminal-input.js').TerminalInput;

package/dist/interfaces/wasi-cli-terminal-stdout.d.ts

@@ -0,0 +1,3 @@
+/** @module Interface wasi:cli/terminal-stdout@0.2.0 **/
+export function getTerminalStdout(): TerminalOutput | undefined;
+export type TerminalOutput = import('./wasi-cli-terminal-output.js').TerminalOutput;

package/dist/interfaces/wasi-clocks-monotonic-clock.d.ts

@@ -0,0 +1,8 @@
+/** @module Interface wasi:clocks/monotonic-clock@0.2.0 **/
+export function now(): Instant;
+export function resolution(): Duration;
+export function subscribeInstant(when: Instant): Pollable;
+export function subscribeDuration(when: Duration): Pollable;
+export type Duration = bigint;
+export type Instant = bigint;
+export type Pollable = import('./wasi-io-poll.js').Pollable;

package/dist/interfaces/wasi-clocks-wall-clock.d.ts

@@ -0,0 +1,7 @@
+/** @module Interface wasi:clocks/wall-clock@0.2.0 **/
+export function now(): Datetime;
+export function resolution(): Datetime;
+export interface Datetime {
+  seconds: bigint,
+  nanoseconds: number,
+}

package/dist/interfaces/wasi-filesystem-preopens.d.ts

@@ -0,0 +1,3 @@
+/** @module Interface wasi:filesystem/preopens@0.2.0 **/
+export function getDirectories(): Array<[Descriptor, string]>;
+export type Descriptor = import('./wasi-filesystem-types.js').Descriptor;

package/dist/interfaces/wasi-filesystem-types.d.ts

@@ -0,0 +1,208 @@
+/** @module Interface wasi:filesystem/types@0.2.0 **/
+export function filesystemErrorCode(err: Error): ErrorCode | undefined;
+export type Filesize = bigint;
+/**
+ * # Variants
+ * 
+ * ## `"normal"`
+ * 
+ * ## `"sequential"`
+ * 
+ * ## `"random"`
+ * 
+ * ## `"will-need"`
+ * 
+ * ## `"dont-need"`
+ * 
+ * ## `"no-reuse"`
+ */
+export type Advice = 'normal' | 'sequential' | 'random' | 'will-need' | 'dont-need' | 'no-reuse';
+/**
+ * # Variants
+ * 
+ * ## `"access"`
+ * 
+ * ## `"would-block"`
+ * 
+ * ## `"already"`
+ * 
+ * ## `"bad-descriptor"`
+ * 
+ * ## `"busy"`
+ * 
+ * ## `"deadlock"`
+ * 
+ * ## `"quota"`
+ * 
+ * ## `"exist"`
+ * 
+ * ## `"file-too-large"`
+ * 
+ * ## `"illegal-byte-sequence"`
+ * 
+ * ## `"in-progress"`
+ * 
+ * ## `"interrupted"`
+ * 
+ * ## `"invalid"`
+ * 
+ * ## `"io"`
+ * 
+ * ## `"is-directory"`
+ * 
+ * ## `"loop"`
+ * 
+ * ## `"too-many-links"`
+ * 
+ * ## `"message-size"`
+ * 
+ * ## `"name-too-long"`
+ * 
+ * ## `"no-device"`
+ * 
+ * ## `"no-entry"`
+ * 
+ * ## `"no-lock"`
+ * 
+ * ## `"insufficient-memory"`
+ * 
+ * ## `"insufficient-space"`
+ * 
+ * ## `"not-directory"`
+ * 
+ * ## `"not-empty"`
+ * 
+ * ## `"not-recoverable"`
+ * 
+ * ## `"unsupported"`
+ * 
+ * ## `"no-tty"`
+ * 
+ * ## `"no-such-device"`
+ * 
+ * ## `"overflow"`
+ * 
+ * ## `"not-permitted"`
+ * 
+ * ## `"pipe"`
+ * 
+ * ## `"read-only"`
+ * 
+ * ## `"invalid-seek"`
+ * 
+ * ## `"text-file-busy"`
+ * 
+ * ## `"cross-device"`
+ */
+export type ErrorCode = 'access' | 'would-block' | 'already' | 'bad-descriptor' | 'busy' | 'deadlock' | 'quota' | 'exist' | 'file-too-large' | 'illegal-byte-sequence' | 'in-progress' | 'interrupted' | 'invalid' | 'io' | 'is-directory' | 'loop' | 'too-many-links' | 'message-size' | 'name-too-long' | 'no-device' | 'no-entry' | 'no-lock' | 'insufficient-memory' | 'insufficient-space' | 'not-directory' | 'not-empty' | 'not-recoverable' | 'unsupported' | 'no-tty' | 'no-such-device' | 'overflow' | 'not-permitted' | 'pipe' | 'read-only' | 'invalid-seek' | 'text-file-busy' | 'cross-device';
+/**
+ * # Variants
+ * 
+ * ## `"unknown"`
+ * 
+ * ## `"block-device"`
+ * 
+ * ## `"character-device"`
+ * 
+ * ## `"directory"`
+ * 
+ * ## `"fifo"`
+ * 
+ * ## `"symbolic-link"`
+ * 
+ * ## `"regular-file"`
+ * 
+ * ## `"socket"`
+ */
+export type DescriptorType = 'unknown' | 'block-device' | 'character-device' | 'directory' | 'fifo' | 'symbolic-link' | 'regular-file' | 'socket';
+export type Error = import('./wasi-io-streams.js').Error;
+export type InputStream = import('./wasi-io-streams.js').InputStream;
+export type OutputStream = import('./wasi-io-streams.js').OutputStream;
+export interface DescriptorFlags {
+  read?: boolean,
+  write?: boolean,
+  fileIntegritySync?: boolean,
+  dataIntegritySync?: boolean,
+  requestedWriteSync?: boolean,
+  mutateDirectory?: boolean,
+}
+export type Datetime = import('./wasi-clocks-wall-clock.js').Datetime;
+export type NewTimestamp = NewTimestampNoChange | NewTimestampNow | NewTimestampTimestamp;
+export interface NewTimestampNoChange {
+  tag: 'no-change',
+}
+export interface NewTimestampNow {
+  tag: 'now',
+}
+export interface NewTimestampTimestamp {
+  tag: 'timestamp',
+  val: Datetime,
+}
+export type LinkCount = bigint;
+export interface DescriptorStat {
+  type: DescriptorType,
+  linkCount: LinkCount,
+  size: Filesize,
+  dataAccessTimestamp?: Datetime,
+  dataModificationTimestamp?: Datetime,
+  statusChangeTimestamp?: Datetime,
+}
+export interface PathFlags {
+  symlinkFollow?: boolean,
+}
+export interface OpenFlags {
+  create?: boolean,
+  directory?: boolean,
+  exclusive?: boolean,
+  truncate?: boolean,
+}
+export interface MetadataHashValue {
+  lower: bigint,
+  upper: bigint,
+}
+export interface DirectoryEntry {
+  type: DescriptorType,
+  name: string,
+}
+
+export class Descriptor {
+  /**
+   * This type does not have a public constructor.
+   */
+  private constructor();
+  readViaStream(offset: Filesize): InputStream;
+  writeViaStream(offset: Filesize): OutputStream;
+  appendViaStream(): OutputStream;
+  advise(offset: Filesize, length: Filesize, advice: Advice): void;
+  syncData(): void;
+  getFlags(): DescriptorFlags;
+  getType(): DescriptorType;
+  setSize(size: Filesize): void;
+  setTimes(dataAccessTimestamp: NewTimestamp, dataModificationTimestamp: NewTimestamp): void;
+  read(length: Filesize, offset: Filesize): [Uint8Array, boolean];
+  write(buffer: Uint8Array, offset: Filesize): Filesize;
+  readDirectory(): DirectoryEntryStream;
+  sync(): void;
+  createDirectoryAt(path: string): void;
+  stat(): DescriptorStat;
+  statAt(pathFlags: PathFlags, path: string): DescriptorStat;
+  setTimesAt(pathFlags: PathFlags, path: string, dataAccessTimestamp: NewTimestamp, dataModificationTimestamp: NewTimestamp): void;
+  linkAt(oldPathFlags: PathFlags, oldPath: string, newDescriptor: Descriptor, newPath: string): void;
+  openAt(pathFlags: PathFlags, path: string, openFlags: OpenFlags, flags: DescriptorFlags): Descriptor;
+  readlinkAt(path: string): string;
+  removeDirectoryAt(path: string): void;
+  renameAt(oldPath: string, newDescriptor: Descriptor, newPath: string): void;
+  symlinkAt(oldPath: string, newPath: string): void;
+  unlinkFileAt(path: string): void;
+  isSameObject(other: Descriptor): boolean;
+  metadataHash(): MetadataHashValue;
+  metadataHashAt(pathFlags: PathFlags, path: string): MetadataHashValue;
+}
+
+export class DirectoryEntryStream {
+  /**
+   * This type does not have a public constructor.
+   */
+  private constructor();
+  readDirectoryEntry(): DirectoryEntry | undefined;
+}

package/dist/interfaces/wasi-io-error.d.ts

@@ -0,0 +1,9 @@
+/** @module Interface wasi:io/error@0.2.0 **/
+
+export class Error {
+  /**
+   * This type does not have a public constructor.
+   */
+  private constructor();
+  toDebugString(): string;
+}

package/dist/interfaces/wasi-io-poll.d.ts

@@ -0,0 +1,11 @@
+/** @module Interface wasi:io/poll@0.2.0 **/
+export function poll(in_: Array<Pollable>): Uint32Array;
+
+export class Pollable {
+  /**
+   * This type does not have a public constructor.
+   */
+  private constructor();
+  ready(): boolean;
+  block(): void;
+}

package/dist/interfaces/wasi-io-streams.d.ts

@@ -0,0 +1,40 @@
+/** @module Interface wasi:io/streams@0.2.0 **/
+export type Error = import('./wasi-io-error.js').Error;
+export type Pollable = import('./wasi-io-poll.js').Pollable;
+export type StreamError = StreamErrorLastOperationFailed | StreamErrorClosed;
+export interface StreamErrorLastOperationFailed {
+  tag: 'last-operation-failed',
+  val: Error,
+}
+export interface StreamErrorClosed {
+  tag: 'closed',
+}
+
+export class InputStream {
+  /**
+   * This type does not have a public constructor.
+   */
+  private constructor();
+  read(len: bigint): Uint8Array;
+  blockingRead(len: bigint): Uint8Array;
+  skip(len: bigint): bigint;
+  blockingSkip(len: bigint): bigint;
+  subscribe(): Pollable;
+}
+
+export class OutputStream {
+  /**
+   * This type does not have a public constructor.
+   */
+  private constructor();
+  checkWrite(): bigint;
+  write(contents: Uint8Array): void;
+  blockingWriteAndFlush(contents: Uint8Array): void;
+  flush(): void;
+  blockingFlush(): void;
+  subscribe(): Pollable;
+  writeZeroes(len: bigint): void;
+  blockingWriteZeroesAndFlush(len: bigint): void;
+  splice(src: InputStream, len: bigint): bigint;
+  blockingSplice(src: InputStream, len: bigint): bigint;
+}

package/dist/interfaces/wasi-random-insecure-seed.d.ts

@@ -0,0 +1,2 @@
+/** @module Interface wasi:random/insecure-seed@0.2.0 **/
+export function insecureSeed(): [bigint, bigint];

package/dist/interfaces/wasi-random-insecure.d.ts

@@ -0,0 +1,3 @@
+/** @module Interface wasi:random/insecure@0.2.0 **/
+export function getInsecureRandomBytes(len: bigint): Uint8Array;
+export function getInsecureRandomU64(): bigint;

package/dist/interfaces/wasi-random-random.d.ts

@@ -0,0 +1,3 @@
+/** @module Interface wasi:random/random@0.2.0 **/
+export function getRandomBytes(len: bigint): Uint8Array;
+export function getRandomU64(): bigint;

package/dist/interfaces/wasi-sockets-instance-network.d.ts

@@ -0,0 +1,3 @@
+/** @module Interface wasi:sockets/instance-network@0.2.0 **/
+export function instanceNetwork(): Network;
+export type Network = import('./wasi-sockets-network.js').Network;