{"id":15438,"library":"geos-wasm","title":"GEOS WebAssembly Bindings","description":"geos-wasm provides a high-performance WebAssembly (WASM) build of GEOS, a robust C/C++ port of the Java Topology Suite (JTS), enabling advanced planar geometry operations directly within JavaScript environments. Currently at version 3.1.1, this library allows developers to leverage a battle-tested geospatial engine without relying on native system dependencies, making it suitable for both browser-based applications and server-side contexts like Node.js, Bun, or Deno. Built using Emscripten, geos-wasm translates GEOS's extensive C/C++ core into an efficient WebAssembly module. Its key differentiator is bringing the full power and precision of GEOS's algorithms—such as buffering, intersection, union, and area calculation—to JavaScript with a minimal setup, abstracting away the complexities of the underlying C/C++ memory management through its WASM interface. While no fixed release cadence is stated, updates typically align with upstream GEOS advancements and community-driven requirements, ensuring access to the latest topological functionalities.","status":"active","version":"3.1.1","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","GEOS","WASM","typescript"],"install":[{"cmd":"npm install geos-wasm","lang":"bash","label":"npm"},{"cmd":"yarn add geos-wasm","lang":"bash","label":"yarn"},{"cmd":"pnpm add geos-wasm","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This is the default export and returns a Promise that resolves to the GEOS object. It must be awaited before using any GEOS functions.","wrong":"const initGeosJs = require('geos-wasm');","symbol":"initGeosJs","correct":"import initGeosJs from 'geos-wasm';"},{"note":"All GEOS functions and memory management utilities (e.g., Module._malloc) are properties of the resolved 'geos' object, not direct imports from the package root.","symbol":"GEOS functions (e.g., GEOSWKTReader_create)","correct":"const geos = await initGeosJs();\nconst reader = geos.GEOSWKTReader_create();"},{"note":"Imports the TypeScript type definition for the GEOS object returned by initGeosJs, providing type-checking for GEOS methods and properties.","symbol":"GEOS Type","correct":"import type { GEOS } from 'geos-wasm';"}],"quickstart":{"code":"import initGeosJs from 'geos-wasm';\n\nasync function runGeosExample() {\n  // Initialize the GEOS WebAssembly module. This returns a promise.\n  const geos = await initGeosJs();\n\n  // Use the GEOS object to call GEOS functions.\n  // Example: Get the area of a polygon defined by WKT.\n\n  // 1. Create a WKT reader.\n  const reader = geos.GEOSWKTReader_create();\n  const wkt = 'POLYGON ((0 0, 1 0, 1 1, 0 1, 0 0))';\n\n  // 2. Allocate memory for the WKT string and write it.\n  const size = wkt.length + 1;\n  const wktPtr = geos.Module._malloc(size);\n  geos.Module.stringToUTF8(wkt, wktPtr, size);\n\n  // 3. Read the WKT string into a GEOS geometry, which returns a pointer to the geometry.\n  const geomPtr = geos.GEOSWKTReader_read(reader, wktPtr);\n\n  // 4. Allocate memory for the result (area) and calculate it.\n  const areaPtr = geos.Module._malloc(8); // 8 bytes for a double\n  geos.GEOSArea(geomPtr, areaPtr);\n\n  // 5. Read the calculated area from the pointer into a JavaScript number.\n  const area = geos.Module.getValue(areaPtr, 'double');\n\n  console.log('Calculated area:', area); // Expected output: Calculated area: 1\n\n  // 6. Crucially, free all allocated GEOS objects and memory pointers.\n  geos.GEOSWKTReader_destroy(reader);\n  geos.GEOSGeom_destroy(geomPtr);\n  geos.GEOSFree(areaPtr); // GEOSFree for values allocated by GEOS\n  geos.Module._free(wktPtr); // Module._free for values allocated by Emscripten's malloc\n}\n\n// Run the example and catch any potential errors.\nrunGeosExample().catch(console.error);","lang":"typescript","description":"Demonstrates initializing the GEOS WASM module, creating a WKT reader, parsing a polygon, calculating its area, and performing crucial manual memory management by freeing allocated resources."},"warnings":[{"fix":"Always ensure that every allocated pointer and created GEOS object (e.g., geometries, readers) is explicitly freed or destroyed once it's no longer needed. Refer to the `quickstart` example for a demonstration of correct cleanup.","message":"geos-wasm requires explicit manual memory management using functions like `geos.Module._malloc()`, `geos.Module._free()`, `geos.GEOSGeom_destroy()`, and `geos.GEOSWKTReader_destroy()`. Failing to free allocated pointers and destroy GEOS objects will lead to memory leaks, which is highly atypical for JavaScript development.","severity":"gotcha","affected_versions":">=3.1.1"},{"fix":"Carefully follow the API documentation for each GEOS function regarding pointer usage and data types. Utilize `geos.Module.stringToUTF8()`, `geos.Module.getValue()`, `geos.Module._malloc()`, and `geos.Module._free()` as demonstrated in examples.","message":"Interaction with GEOS functions often involves passing and receiving raw memory pointers, requiring a C-like programming paradigm not common in JavaScript. Developers must understand how to allocate memory, write data to pointers, and read values from them using `geos.Module` utilities.","severity":"gotcha","affected_versions":">=3.1.1"},{"fix":"Always `await` the `initGeosJs()` call, e.g., `const geos = await initGeosJs();` within an `async` function, ensuring the GEOS object is ready before use.","message":"The `initGeosJs()` function is asynchronous and returns a Promise. All GEOS operations must be performed only after this Promise has successfully resolved to the GEOS object, otherwise `TypeError`s will occur due to attempts to access properties of an undefined or unresolved object.","severity":"gotcha","affected_versions":">=3.1.1"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure `const geos = await initGeosJs();` is called and successfully resolves within an `async` context before attempting to access any `geos` methods.","cause":"The `initGeosJs()` function, which initializes the WebAssembly module and returns the GEOS object, was not awaited or has not yet resolved before its methods were accessed.","error":"TypeError: Cannot read properties of undefined (reading 'GEOSWKTReader_create')"},{"fix":"Thoroughly review your code to ensure all GEOS objects are destroyed (`geos.GEOSGeom_destroy()`, `geos.GEOSWKTReader_destroy()`) and all manually allocated pointers are freed (`geos.Module._free()`, `geos.GEOSFree()`) once they are no longer needed.","cause":"GEOS objects (geometries, readers) or manually allocated memory pointers (`_malloc`) are not being explicitly freed or destroyed after use, leading to unmanaged memory growth within the WebAssembly module.","error":"Memory leak detected in performance profiler / Application consumes increasing amounts of RAM over time."},{"fix":"Configure your Node.js project for ESM by adding `\"type\": \"module\"` to your `package.json`, or rename your file to `.mjs`. If you must use CommonJS, consider dynamic `import()`: `const { default: initGeosJs } = await import('geos-wasm');`","cause":"You are attempting to use ESM `import` syntax in a CommonJS environment (e.g., a `.js` file without `\"type\": \"module\"` in `package.json`, or a `.cjs` file in Node.js).","error":"SyntaxError: Cannot use import statement outside a module"}],"ecosystem":"npm"}