Add memory util functions

CHANGELOG.md

@@ -1,6 +1,11 @@
 # PDFium.js Changelog
 
-## v0.2.0 (2024-01-19)
+## v0.2.1-rc.1 (2024-01-20)
+
+- Add memory util functions
+  - added functions: `fill`, `getData`, `calloc`
+
+## v0.2.0-rc.1 (2024-01-19)
 
 - Upgrade pdfium WebAssembly binary version to 6183
 - Embed wasm binary in loader file

README.md

@@ -56,17 +56,27 @@ PDFium().then((PDFiumModule) => {
 });
 ```
 
-### Memory Management
+### WASM Memory Management
+
+Here is simple code snippets about memory management.
+
+The WASM Memory can be found in `PDFiumModule.FPDF.HEAP*` properties.
 
 ```ts
-import { PDFium } from "pdfium.js";
+import { PDFium, memory } from "pdfium.js";
 
 // options parameter can be skipped after the module loaded
 PDFium().then((PDFiumModule) => {
-  const bytes = 1024;
+  const nBytes = 1024;
+
+  // allocate 1024 bytes in wasm memory
+  const memoryAddress = PDFiumModule.wasmExports.malloc(nBytes);
+
+  // you can also use calloc() to allocate 1024 bytes (array of 256 integers)
+  const memoryAddress2 = memory.calloc(256, 4);
 
-  // allocate 1024 bytes in memory
-  const memoryAddress = PDFiumModule.wasmExports.malloc(bytes);
+  // zero-fill allocated memory
+  memory.fill(PDFiumModule.FPDF.HEAPU8, memoryAddress, nBytes);
 
   // free memory
   PDFiumModule.wasmExports.free(memoryAddress);

package.json

@@ -1,6 +1,6 @@
 {
   "name": "pdfium.js",
-  "version": "0.2.0-rc.1",
+  "version": "0.2.1-rc.1",
   "description": "A PDFium wrapper library for browser-side JavaScript",
   "main": "./dist/cjs/index.js",
   "types": "./dist/esm/index.d.ts",

src/index.ts

@@ -1,8 +1,9 @@
 import createPDFiumModule from "./libs/pdfium";
 import type { FPDF } from "./global";
+import * as memory from "./memory";
 
 /**
- * Emscripten module options type definition
+ * Emscripten module options type definition.
  */
 interface ModuleOptions {
   [key: string]: unknown;
@@ -61,5 +62,5 @@ const PDFium = (options: LibraryOptions = {}) => {
 };
 
 export * from "./constants";
-export { createPDFium, FPDF, PDFium };
+export { createPDFium, FPDF, PDFium, memory };
 export default PDFium;

src/memory.ts

@@ -0,0 +1,47 @@
+type MemoryType =
+  | Int8Array
+  | Int16Array
+  | Int32Array
+  | Uint8Array
+  | Uint16Array
+  | Uint32Array
+  | Float32Array
+  | Float64Array;
+
+/**
+ * Fill specified range of wasm memory with single value.
+ *
+ * @param memory target awsm memory
+ * @param offset start offset of range
+ * @param size number of values to fill from offset
+ * @param fillValue value to fill memory
+ */
+export function fill(memory: MemoryType, offset: number, size: number, fillValue: number) {
+  memory.fill(fillValue, offset, offset + size);
+}
+
+/**
+ * Get ranged data from wasm memory.
+ *
+ * @param memory target wasm memory
+ * @param offset start offset of range
+ * @param size number of values to get from offset
+ * @returns result of ranged data as `TypedArray`
+ */
+export function getData(memory: MemoryType, offset: number, size: number) {
+  return memory.subarray(offset, offset + size);
+}
+
+/**
+ * Allocate wasm memory for an array of num objects of size and initialize allocated memory range to zero-fill.
+ *
+ * @param num number of objects
+ * @param type size of object
+ * @returns allocated memory pointer
+ */
+export function calloc(num: number, type: number) {
+  const ptr = window.FPDF.wasmExports.malloc(num * type);
+  fill(window.FPDF.HEAP8, ptr, num * type, 0);
+
+  return ptr;
+}