@molcrafts/molrs 0.0.1 → 0.0.4

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, MolCrafts
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,175 +1,72 @@
-# molrs-wasm: WASM bindings for molrs
+# molrs-wasm
 
-Object-oriented WASM bindings for molrs using FFI handle-based architecture.
+WASM bindings for `molrs`, aimed at browser and JavaScript/TypeScript consumers.
 
-## Quick Start
+## Local build
 
-```javascript
-import init, { Frame, XyzReader } from './pkg/molrs.js';
-
-await init();
-
-// Create a new frame
-const frame = new Frame();
-const atoms = frame.createBlock("atoms");
-
-// Set column data
-atoms.setColumnF32("x", new Float32Array([1.0, 2.0, 3.0]));
-const data = atoms.getColumnF32("x");
-
-// Read from file
-const reader = new XyzReader(fileContent);
-const loadedFrame = reader.read(0);
+```bash
+wasm-pack build --target web
+bash scripts/postprocess-pkg.sh
 ```
 
-## API Reference
+This produces `pkg/molwasm.js` plus `pkg/typed-views.js` for local use.
 
-### Frame
+## npm package
 
-The main container for molecular data.
+The published package is `@molcrafts/molrs`.
 
 ```javascript
-const frame = new Frame();
-
-// Create a block
-const atoms = frame.createBlock("atoms");
-
-// Get an existing block
-const atomsAgain = frame.getBlock("atoms");
-
-// Remove a block
-frame.removeBlock("atoms");
-
-// Clear all blocks
-frame.clear();
-
-// Drop the frame (invalidates all blocks)
-frame.drop();
-```
-
-### Block
-
-A block contains columnar data with consistent row counts.
-
-```javascript
-const block = frame.createBlock("atoms");
-
-// Set column data
-const positions = new Float32Array([1.0, 2.0, 3.0, 4.0, 5.0, 6.0]);
-const shape = new Uint32Array([2, 3]); // 2 atoms, 3 coordinates each
-block.setColumnF32("positions", positions, shape);
+import init, { Frame, WasmArray, XyzReader, writeFrame } from "@molcrafts/molrs";
+import { typedArrayView } from "@molcrafts/molrs/typed-views";
 
-// Set integer columns (e.g., atom ids or bond indices)
-const ids = new BigInt64Array([1n, 2n, 3n]);
-block.setColumnI64("id", ids);
-
-// Get column data (returns copy)
-const data = block.getColumnF32("positions"); // Float32Array
-const idData = block.getColumnI64("id"); // BigInt64Array
-
-// Get column with shape info
-const { data, shape } = block.getColumnF32WithShape("positions");
-
-// Query block info
-const keys = block.keys(); // ["positions"]
-const nrows = block.nrows(); // 2
-```
+await init();
 
-## File I/O
+const frame = new Frame();
+const atoms = frame.createBlock("atoms");
+atoms.set("x", new Float32Array([0.0, 1.0, 2.0]));
 
-### Reading Files
+const xView = atoms.view("x");
+const xTyped = typedArrayView(xView); // Float32Array
 
-```javascript
-// XYZ files
-const xyzReader = new XyzReader(fileContent);
-const frameCount = xyzReader.len();
-const frame = xyzReader.read(0); // Read frame 0
-
-// PDB files
-const pdbReader = new PdbReader(pdbContent);
-const frame2 = pdbReader.read(0);
-
-// LAMMPS data files
-const lammpsReader = new LammpsReader(lammpsContent);
-const frame3 = lammpsReader.read(0);
+const xyz = writeFrame(frame, "xyz");
+console.log(xyz);
 ```
 
-### Writing Files
+## Local file usage
 
 ```javascript
-// TODO: Writer API needs implementation
-// const output = writeFrame(frame, "xyz");
-```
-
-## TypeScript Example
-
-```typescript
-import init, { Frame, Block, XyzReader } from './pkg/molrs.js';
+import init, { Frame, WasmArray, XyzReader, writeFrame } from "./pkg/molwasm.js";
+import { typedArrayView, columnViewMeta } from "./pkg/typed-views.js";
 
 await init();
 
-// Create frame and block
-const frame: Frame = new Frame();
-const atoms: Block = frame.createBlock("atoms");
-
-// Set positions
-const positions = new Float32Array([
-  0.0, 0.0, 0.0,  // atom 1
-  1.0, 0.0, 0.0,  // atom 2
-  0.0, 1.0, 0.0,  // atom 3
-]);
-atoms.setColumnF32("x", positions);
+const frame = new Frame();
+const atoms = frame.createBlock("atoms");
+atoms.set("x", new Float32Array([0.0, 1.0, 2.0]));
 
-// Query data
-const nAtoms = atoms.nrows(); // 3
-const x = atoms.getColumnF32("x");
-console.log(x[0]); // 0.0
+const xCopy = atoms.view("x").toCopy();
+const xView = atoms.view("x");
+const xTypedArray = typedArrayView(xView); // Float32Array | Uint32Array | Uint8Array
+const xMeta = columnViewMeta(xView);
 
-// Read from file
+const arr = WasmArray.from(new Float32Array([0, 0, 0, 1, 0, 0]), new Uint32Array([2, 3]));
 const reader = new XyzReader(fileContent);
-const loadedFrame = reader.read(0);
-if (loadedFrame) {
-  const loadedAtoms = loadedFrame.getBlock("atoms");
-  if (loadedAtoms) {
-    console.log(`Loaded ${loadedAtoms.nrows()} atoms`);
-  }
-}
+const loaded = reader.read(0);
+const xyz = writeFrame(frame, "xyz");
 ```
 
-## Handle Invalidation
-
-Handles follow strict invalidation rules:
-
-- **Block handles** become invalid when:
-  - The parent frame is dropped
-  - The block is removed from the frame
-  - The frame is cleared
-
-- **Frame handles** become invalid when:
-  - `frame.drop()` is called
-
-Attempting to use an invalid handle will throw an error.
+## API surface
 
-## Architecture
-
-This WASM layer is a thin wrapper around `molrs-ffi`, which provides:
-- Stable handle-based references (no raw pointers)
-- Explicit invalidation semantics
-- Consistent behavior across Python and WASM
-
-The API is designed to be:
-- **Object-oriented**: Natural class hierarchy (Frame → Block)
-- **Type-safe**: Clear ownership and lifetime semantics
-- **Explicit**: No hidden copies or implicit conversions
-- **Simple**: Store is hidden - Frame is the main entry point
+- `Frame`, `Block`, `ColumnView`, `WasmArray`
+- `typed-views.js` helpers for `ptr + len + shape + dtype`
+- `Box`
+- `XyzReader`, `PdbReader`, `LammpsReader`
+- `SimulationReader`
+- `writeFrame(frame, "xyz" | "pdb")`
 
 ## Testing
 
 ```bash
 cargo test -p molrs-wasm --lib
-```
-
-For WASM-specific tests:
-```bash
-wasm-pack test --node wasm
+wasm-pack test --node
 ```