@fayzanx/mmap-io 1.6.12

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Oscar Campbell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,117 @@
+
+# mmap-io - Node.js memory mapping bindings
+
+## Note
+- This is a fork of [ARyaskov/mmap-io](https://github.com/ARyaskov/mmap-io) -> [ozra/mmap-io](https://github.com/ozra/mmap-io) and [ipinfo/mmap-utils](https://github.com/ipinfo/mmap-utils)
+
+## Quick info
+
+- Long story short: with this addon you can increase performance of your file interactions by memory mapping files, 
+you are "project" some file to RAM and push data to RAM without any interactions with hdd/ssd subsystem -- this module will
+facilitate reliable syncing between RAM-file and disk-file.
+- **mmap-io** is written in C++17 and TypeScript, when you're installing it in your project, you're automatically getting 
+a precompiled binary (.node-file) for your platform from Downloads section of this project. 
+Otherwise it requires a C++17 compiler and Python 3.12+ on your machine to build.
+- **mmap-io** is tested on Node.js 16 (16.14+), 18, 19, 20, 21, 22. Sorry, but there is no Node.js 17 because of some compilation stage issues.
+- **mmap-io** has built binaries for Windows x86_64, Linux x86_64, Mac x86_64, Mac ARM.
+- Potential use cases: working with big files (like highly volatile game map files), pushing data to cache files, video/audio-processing, messaging mechanics for inter-process communication.
+
+## Quick TS example
+
+```typescript
+    import fs from "fs"
+    import mmap from "@fayzanx/mmap-io"
+    
+    const file = fs.openSync("/home/ubuntu/some-file-here", "r+")
+    const buf = mmap.map(fs.fstatSync(file).size, mmap.PROT_WRITE, mmap.MAP_SHARED, file)
+    mmap.advise(buf, mmap.MADV_RANDOM)
+    // Now you can work with "buf" as with a regular Buffer object.
+    // All your changes will be synced with the file "some-file-here" on disk.
+    // For example, add number 1024 at 0 position of buffer:
+    // buf.writeUInt32LE(1024, 0)
+
+```
+
+
+# Fork Notice
+
+This is a fork of mmap-io (https://github.com/Widdershin/mmap-io/), as the upstream repo is no longer maintained and it didn't compile well on my machine for newer Node.js.
+
+This version of mmap-io builds on Node up to 22, and provides binaries for Windows and macOS via @mapbox/node-pre-gyp.
+
+# Author's notice: 
+## Mmap for Node.js
+mmap(2) / madvise(2) / msync(2) / mincore(2) for node.js revisited.
+
+**NOTE**: this is a fork of https://github.com/ozra/mmap-io as that repo is
+unmaintained.
+
+# Installation
+
+## npm
+
+This is my first node.js addon and after hours wasted reading up on V8 API I luckily stumbled upon [Native Abstractions for Node](https://github.com/rvagg/nan). Makes life so much easier. Hot tip!
+
+_mmap-io_ is written in C++11 and ~~[LiveScript](https://github.com/gkz/LiveScript)~~ — _although I love LS, it's more prudent to use TypeScript for a library, so I've rewritten that code._
+
+It should be noted that mem-mapping is by nature potentially blocking, and _should not be used in concurrent serving/processing applications_, but rather has it's niche where multiple processes are working on the same giant sets of data (thereby sparing physical memory, and load times if the kernel does it's job for read ahead), preferably multiple readers and single or none concurrent writer, to not spoil the gains by shitloads of spin-locks, mutexes or such. _And your noble specific use case of course._
+
+
+# News and Updates
+
+### 2024-05-12: version 1.4.3
+- Add support for Node 22
+
+# Install
+Use npm or yarn or git.
+
+```bash
+$ npm install @fayzanx/mmap-io
+```
+```bash
+$ yarn add @fayzanx/mmap-io
+```
+
+```bash
+$ git clone https://github.com/fayzanx/mmap-io.git
+$ cd mmap-io
+$ yarn build
+$ yarn install
+```
+
+### Good to Know (TM)
+
+- Checkout man pages mmap(2), madvise(2), msync(2), mincore(2) for more detailed intell.
+- The mappings are automatically unmapped when the buffer is garbage collected.
+- Write-mappings need the fd to be opened with "r+", or you'll get a permission error (13).
+- If you make a read-only mapping and then ignorantly set a value in the buffer, all hell previously unknown to a JS'er breaks loose (segmentation fault). It is possible to write some devilous code to intercept the SIGSEGV and throw an exception, but let's not do that!
+- `Offset`, and in some cases `length` needs to be a multiple of mmap-io.PAGESIZE (which commonly is 4096)
+- Huge pages are only supported for anonymous / private mappings (well, in Linux), so I didn't throw in flags for that since I found no use.
+- As Ben Noordhuis previously has stated: Supplying hint for a fixed virtual memory adress is kinda moot point in JS, so not supported.
+- If you miss a feature - contribute! Or request it in an issue.
+- If documentation isn't clear, make an issue.
+
+
+# Tests
+
+```bash
+$ yarn test
+```
+
+### Misc
+
+- Checkout man pages `mmap(2)`, `madvise(2)`, `msync(2)`, `mincore(2)` for more
+  detailed intel.
+- The mappings are automatically unmapped when the buffer is garbage collected.
+- Write-mappings need the fd to be opened with "r+", or you'll get a permission
+  error (13).
+- If you make a read-only mapping and then ignorantly set a value in the
+  buffer, all hell previously unknown to a JS'er breaks loose (segmentation
+  fault). It is possible to write some devilous code to intercept the SIGSEGV
+  and throw an exception, but let's not do that!
+- `Offset`, and in some cases `length` needs to be a multiple of `PAGESIZE`
+  (which commonly is 4096)
+- Huge pages are only supported for anonymous / private mappings (well, in
+  Linux), so I didn't throw in flags for that since I found no use.
+- As Ben Noordhuis previously has stated: Supplying hint for a fixed virtual
+  memory adress is kinda moot point in JS, so not supported.

package/binding.gyp

@@ -0,0 +1,32 @@
+{
+    "targets": [{
+        "target_name": "mmap_io",
+        "sources": [ "src/mmap-io.cc" ],
+        "include_dirs": [
+            "<!(node -e \"require('nan')\")"
+        ],
+        "cflags_cc": [
+            "-std=c++17"
+        ],
+        "conditions": [
+            [ 'OS=="mac"',
+                { "xcode_settings": {
+                    'OTHER_CPLUSPLUSFLAGS' : ['-std=c++17','-stdlib=libc++'],
+                    'OTHER_LDFLAGS': ['-stdlib=libc++'],
+                    'MACOSX_DEPLOYMENT_TARGET': '10.8'
+                }}
+            ]
+        ]
+    },
+    {
+      "target_name": "action_after_build",
+      "type": "none",
+      "dependencies": [ "<(module_name)" ],
+      "copies": [
+        {
+          "files": [ "<(PRODUCT_DIR)/<(module_name).node" ],
+          "destination": "<(module_path)"
+        }
+      ]
+    }]
+}

package/dist/mmap-io.d.ts

@@ -0,0 +1,29 @@
+type FileDescriptor = number;
+type MapProtectionFlags = MmapIo["PROT_NONE"] | MmapIo["PROT_READ"] | MmapIo["PROT_WRITE"] | MmapIo["PROT_EXEC"] | 3 | 5 | 6 | 7;
+type MapFlags = MmapIo["MAP_SHARED"] | MmapIo["MAP_PRIVATE"] | MmapIo["MAP_ANONYMOUS"] | MmapIo["MAP_POPULATE"] | MmapIo["MAP_NONBLOCK"] | number;
+type MapAdvise = MmapIo["MADV_NORMAL"] | MmapIo["MADV_RANDOM"] | MmapIo["MADV_SEQUENTIAL"] | MmapIo["MADV_WILLNEED"] | MmapIo["MADV_DONTNEED"];
+type MmapIo = {
+    map(size: number, protection: MapProtectionFlags, flags: MapFlags, fd: FileDescriptor, offset?: number, advise?: MapAdvise, name?: Buffer): Buffer;
+    advise(buffer: Buffer, offset: number, length: number, advise: MapAdvise): void;
+    advise(buffer: Buffer, advise: MapAdvise): void;
+    incore(buffer: Buffer): [number, number];
+    sync(buffer: Buffer, offset?: number, size?: number, blocking_sync?: boolean, invalidate_pages?: boolean): void;
+    sync(buffer: Buffer, blocking_sync: boolean, invalidate_pages?: boolean): void;
+    readonly PROT_READ: 1;
+    readonly PROT_WRITE: 2;
+    readonly PROT_EXEC: 4;
+    readonly PROT_NONE: 0;
+    readonly MAP_SHARED: 1;
+    readonly MAP_PRIVATE: 2;
+    readonly MAP_ANONYMOUS: 32;
+    readonly MAP_POPULATE: 32768;
+    readonly MAP_NONBLOCK: 65536;
+    readonly MADV_NORMAL: 0;
+    readonly MADV_RANDOM: 1;
+    readonly MADV_SEQUENTIAL: 2;
+    readonly MADV_WILLNEED: 3;
+    readonly MADV_DONTNEED: 4;
+    readonly PAGESIZE: number;
+};
+declare const mmap: MmapIo;
+export default mmap;

package/dist/mmap-io.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const binary = require('@mapbox/node-pre-gyp');
+const path = require('path');
+const binding_path = binary.find(path.resolve(path.join(__dirname, '../package.json')));
+const mmap_lib_raw_ = require(binding_path);
+// snatch the raw C++-sync func
+const raw_sync_fn_ = mmap_lib_raw_.sync_lib_private__;
+// Hide the original C++11 func from users
+delete mmap_lib_raw_.sync_lib_private__;
+// Take care of all the param juggling here instead of in C++ code, by making
+// some overloads, and doing some argument defaults
+mmap_lib_raw_.sync = function (buf, par_a, par_b, par_c, par_d) {
+    if (typeof par_a === "boolean") {
+        raw_sync_fn_(buf, 0, buf.length, par_a, par_b || false);
+    }
+    else {
+        raw_sync_fn_(buf, par_a || 0, par_b || buf.length, par_c || false, par_d || false);
+    }
+};
+// mmap_lib_raw_.sync = sync_
+const mmap = mmap_lib_raw_;
+module.exports = mmap;
+exports.default = mmap;

package/dist/test.js

@@ -0,0 +1,153 @@
+// Generated by LiveScript 1.6.0
+var fs, os, mmap, assert, constants, say, PAGESIZE, PROT_READ, PROT_WRITE, MAP_SHARED, e, fd, size, buffer, out, i$, ix, incore_stats, WRONG_PAGE_SIZE, testFile, testSize, fdW, wBuffer, fdR, rBuffer, i, val;
+fs = require("fs");
+os = require("os");
+mmap = require("../");
+assert = require("assert");
+constants = require("constants");
+say = function(){
+  var args, res$, i$, to$;
+  res$ = [];
+  for (i$ = 0, to$ = arguments.length; i$ < to$; ++i$) {
+    res$.push(arguments[i$]);
+  }
+  args = res$;
+  return console.log.apply(console, args);
+};
+say("mmap in test is", mmap);
+PAGESIZE = mmap.PAGESIZE, PROT_READ = mmap.PROT_READ, PROT_WRITE = mmap.PROT_WRITE, MAP_SHARED = mmap.MAP_SHARED;
+try {
+  say("mmap.PAGESIZE = ", mmap.PAGESIZE, "tries to overwrite it with 47");
+  mmap.PAGESIZE = 47;
+  say("now mmap.PAGESIZE should be the same:", mmap.PAGESIZE, "silently kept");
+} catch (e$) {
+  e = e$;
+  say("Caught trying to modify the mmap-object. Does this ever happen?", e);
+}
+fd = fs.openSync(process.argv[1], 'r');
+size = fs.fstatSync(fd).size;
+say("file size", size);
+buffer = mmap.map(size, PROT_READ, MAP_SHARED, fd, 0, mmap.MADV_SEQUENTIAL);
+say("buflen 1 = ", buffer.length);
+assert.equal(buffer.length, size);
+say("Give advise with 2 args");
+mmap.advise(buffer, mmap.MADV_NORMAL);
+say("Give advise with 4 args");
+mmap.advise(buffer, 0, mmap.PAGESIZE, mmap.MADV_NORMAL);
+say("\n\nBuffer contents, read byte for byte backwards and see that nothing explodes:\n");
+try {
+  out = "";
+  for (i$ = size - 1; i$ >= 0; --i$) {
+    ix = i$;
+    out += String.fromCharCode(buffer[ix]);
+  }
+  incore_stats = mmap.incore(buffer);
+  assert.equal(incore_stats[0], 0);
+  assert.equal(incore_stats[1], 2);
+} catch (e$) {
+  e = e$;
+  if (e.message !== 'mincore() not implemented') {
+    assert(false, "Shit happened while reading from buffer");
+  }
+}
+try {
+  say("read out of bounds test");
+  assert.equal(typeof buffer[size + 47], "undefined");
+} catch (e$) {
+  e = e$;
+  say("deliberate out of bounds, caught exception - does this thing happen?", e.code, 'err-obj = ', e);
+}
+buffer = mmap.map(size, PROT_READ, MAP_SHARED, fd, 0);
+say("buflen test 5-arg map call = ", buffer.length);
+assert.equal(buffer.length, size);
+buffer = mmap.map(size, PROT_READ, MAP_SHARED, fd);
+say("buflen test 4-arg map call = ", buffer.length);
+assert.equal(buffer.length, size);
+if (os.type() !== 'Windows_NT') {
+  fd = fs.openSync(process.argv[1], 'r');
+  buffer = mmap.map(size, PROT_READ, MAP_SHARED, fd, PAGESIZE);
+  say("buflen test 3 = ", buffer.length);
+  assert.equal(buffer.length, size);
+}
+fd = fs.openSync(process.argv[1], 'r');
+try {
+  buffer = mmap.map("foo", PROT_READ, MAP_SHARED, fd, 0);
+} catch (e$) {
+  e = e$;
+  say("Pass faulty arg - caught deliberate exception: " + e.message);
+}
+fd = fs.openSync(process.argv[1], 'r');
+try {
+  buffer = mmap.map(0, PROT_READ, MAP_SHARED, fd, 0);
+} catch (e$) {
+  e = e$;
+  say("Pass zero size - caught deliberate exception: " + e.message);
+}
+WRONG_PAGE_SIZE = PAGESIZE - 1;
+fd = fs.openSync(process.argv[1], 'r');
+try {
+  buffer = mmap.map(size, PROT_READ, MAP_SHARED, fd, WRONG_PAGE_SIZE);
+} catch (e$) {
+  e = e$;
+  say("Pass wrong page-size as offset - caught deliberate exception: " + e.message);
+}
+fd = fs.openSync(process.argv[1], 'r');
+try {
+  buffer = mmap.map(size, PROT_READ, MAP_SHARED, fd);
+  mmap.advise(buffer, "fuck off");
+} catch (e$) {
+  e = e$;
+  say("Pass faulty arg to advise() - caught deliberate exception: " + e.message);
+}
+say("Now for some write/read tests");
+try {
+  say("Creates file");
+  testFile = "./tmp-mmap-file";
+  testSize = 47474;
+  fs.writeFileSync(testFile, "");
+  fs.truncateSync(testFile, testSize);
+  say("open write buffer");
+  fdW = fs.openSync(testFile, 'r+');
+  say("fd-write = ", fdW);
+  wBuffer = mmap.map(testSize, PROT_WRITE, MAP_SHARED, fdW);
+  fs.closeSync(fdW);
+  mmap.advise(wBuffer, mmap.MADV_SEQUENTIAL);
+  say("open read bufer");
+  fdR = fs.openSync(testFile, 'r');
+  rBuffer = mmap.map(testSize, PROT_READ, MAP_SHARED, fdR);
+  fs.closeSync(fdR);
+  mmap.advise(rBuffer, mmap.MADV_SEQUENTIAL);
+  say("verify write and read");
+  for (i$ = 0; i$ < testSize; ++i$) {
+    i = i$;
+    val = 32 + i % 60;
+    wBuffer[i] = val;
+    assert.equal(rBuffer[i], val);
+  }
+  say("Write/read verification seemed to work out");
+} catch (e$) {
+  e = e$;
+  say("Something fucked up in the write/read test::", e.message);
+}
+try {
+  say("sync() tests x 4");
+  say("1. Does explicit blocking sync to disk");
+  mmap.sync(wBuffer, 0, testSize, true, false);
+  say("2. Does explicit blocking sync without offset/length arguments");
+  mmap.sync(wBuffer, true, false);
+  say("3. Does explicit sync to disk without blocking/invalidate flags");
+  mmap.sync(wBuffer, 0, testSize);
+  say("4. Does explicit sync with no additional arguments");
+  mmap.sync(wBuffer);
+} catch (e$) {
+  e = e$;
+  say("Something fucked up for syncs::", e.message);
+}
+try {
+  fs.unlinkSync(testFile);
+} catch (e$) {
+  e = e$;
+  say("Failed to remove test-file", testFile);
+}
+say("\nAll done");
+process.exit(0);

package/dist/test.types.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test.types.js

@@ -0,0 +1,17 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const mmap_io_1 = __importDefault(require("./mmap-io"));
+const fs_1 = __importDefault(require("fs"));
+const fd = fs_1.default.openSync(__filename, "r+");
+/**
+ * Writing, for instance `4` instead of ie `2` (MADV_SEQUENTIAL), here, will
+ * give an error already while typing (provided language-server is setup)
+ * because of the specific types
+ *
+ * A problem arise with the traditional dirty technique of binary-or, widening
+ * the type from literal to number-field
+ */
+mmap_io_1.default.map(100, (mmap_io_1.default.PROT_EXEC | mmap_io_1.default.PROT_READ), mmap_io_1.default.MAP_SHARED, fd, 0, mmap_io_1.default.MADV_SEQUENTIAL);

package/mmap-io.d.ts

@@ -0,0 +1,29 @@
+type FileDescriptor = number;
+type MapProtectionFlags = MmapIo["PROT_NONE"] | MmapIo["PROT_READ"] | MmapIo["PROT_WRITE"] | MmapIo["PROT_EXEC"] | 3 | 5 | 6 | 7;
+type MapFlags = MmapIo["MAP_SHARED"] | MmapIo["MAP_PRIVATE"] | MmapIo["MAP_ANONYMOUS"] | MmapIo["MAP_POPULATE"] | MmapIo["MAP_NONBLOCK"] | number;
+type MapAdvise = MmapIo["MADV_NORMAL"] | MmapIo["MADV_RANDOM"] | MmapIo["MADV_SEQUENTIAL"] | MmapIo["MADV_WILLNEED"] | MmapIo["MADV_DONTNEED"];
+type MmapIo = {
+    map(size: number, protection: MapProtectionFlags, flags: MapFlags, fd: FileDescriptor, offset?: number, advise?: MapAdvise, name?: Buffer): Buffer;
+    advise(buffer: Buffer, offset: number, length: number, advise: MapAdvise): void;
+    advise(buffer: Buffer, advise: MapAdvise): void;
+    incore(buffer: Buffer): [number, number];
+    sync(buffer: Buffer, offset?: number, size?: number, blocking_sync?: boolean, invalidate_pages?: boolean): void;
+    sync(buffer: Buffer, blocking_sync: boolean, invalidate_pages?: boolean): void;
+    readonly PROT_READ: 1;
+    readonly PROT_WRITE: 2;
+    readonly PROT_EXEC: 4;
+    readonly PROT_NONE: 0;
+    readonly MAP_SHARED: 1;
+    readonly MAP_PRIVATE: 2;
+    readonly MAP_ANONYMOUS: 32;
+    readonly MAP_POPULATE: 32768;
+    readonly MAP_NONBLOCK: 65536;
+    readonly MADV_NORMAL: 0;
+    readonly MADV_RANDOM: 1;
+    readonly MADV_SEQUENTIAL: 2;
+    readonly MADV_WILLNEED: 3;
+    readonly MADV_DONTNEED: 4;
+    readonly PAGESIZE: number;
+};
+declare const mmap: MmapIo;
+export default mmap;

package/mmap-io.js

@@ -0,0 +1 @@
+module.exports = require("./dist/mmap-utils")

package/package.json

@@ -0,0 +1,91 @@
+{
+    "name": "@fayzanx/mmap-io",
+    "version": "1.6.12",
+    "license": "MIT",
+    "author": {
+        "name": "Fayzan Ahmad",
+        "email": "fayzanx@gmail.com",
+        "url": "https://github.com/fayzanx"
+    },
+    "contributors": [
+        {
+            "name": "Oscar Campbell",
+            "email": "oscar@campbell.nu",
+            "url": "https://github.com/ozra"
+        }
+    ],
+    "binary": {
+        "module_name": "mmap_io",
+        "module_path": "./build/binding/{configuration}/{node_abi}-{platform}-{arch}/",
+        "remote_path": "./{version}/",
+        "package_name": "{module_name}-v{version}-{node_abi}-{platform}-{arch}.tar.gz",
+        "host": "https://github.com/fayzanx/mmap-io/releases/download/"
+    },
+    "description": "Node.js mmap bindings revisited.",
+    "homepage": "https://github.com/fayzanx/mmap-io",
+    "keywords": [
+        "low level",
+        "file",
+        "memory mapped",
+        "mmap",
+        "madvise",
+        "sync",
+        "shared memory",
+        "C++",
+        "performance"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/fayzanx/mmap-io.git"
+    },
+    "bugs": {
+        "url": "http://github.com/fayzanx/mmap-io/issues"
+    },
+    "main": "mmap-io.js",
+    "files": [
+        "binding.gyp",
+        "LICENSE",
+        "dist",
+        "mmap-io.d.ts",
+        "mmap-io.js",
+        "package.json",
+        "package-lock.json",
+        "README.md",
+        "src"
+    ],
+    "bin": {
+        "node-pre-gyp-github": "./bin/node-pre-gyp-github"
+    },
+    "scripts": {
+        "clean": "rm -rf build dist",
+        "build": "npm run build-addon && npm run build-es",
+        "build-addon": "node-pre-gyp install --fallback-to-build",
+        "build-es": "run-script-os",
+        "build-es:win32": "tsc && copy .\\dist\\mmap-io.d.ts .\\",
+        "build-es:default": "tsc && cp ./dist/mmap-io.d.ts ./",
+        "rebuild": "node-pre-gyp reinstall --build-from-source",
+        "prepare": "npm run build",
+        "install": "npm run build-addon",
+        "build-binary-x64": "node-pre-gyp rebuild && node-pre-gyp package",
+        "build-binary-x86": "node-pre-gyp rebuild --target_arch=ia32 && node-pre-gyp package --target_arch=ia32",
+        "publish:github": "node-pre-gyp-github publish",
+        "publish:npm": "npm publish --access public --registry=https://registry.npmjs.org",
+        "publish:all": "npm run publish:github || npm run publish:npm",
+        "test": "echo 'tests disabled\n'",
+        "watch": "while true; do (npm run build; inotifywait -qre close_write,moved_to --exclude '\\.git' ./src/; ) done;"
+    },
+    "devDependencies": {
+        "@types/node": "^18.19.41",
+        "node-pre-gyp-github": "^2.0.0",
+        "tsx": "^4.16.2",
+        "typescript": "^5.5.3"
+    },
+    "dependencies": {
+        "@mapbox/node-pre-gyp": "^1.0.11",
+        "errno": "*",
+        "nan": "^2.20.0",
+        "node-gyp": "^10.1.0",
+        "run-script-os": "^1.1.1",
+        "yarn": "^1.22.22"
+    }
+}

package/src/mman.h

@@ -0,0 +1,109 @@
+#include <io.h>
+#include <errno.h>
+#include <windows.h>
+#include <sys/types.h>
+
+#define PROT_NONE       0x00
+#define PROT_READ       0x01
+#define PROT_WRITE      0x02
+#define PROT_EXEC       0x04
+
+#define MAP_FILE        0x00
+#define MAP_SHARED      0x01
+#define MAP_PRIVATE     0x02
+#define MAP_TYPE        0x0F
+#define MAP_ANONYMOUS   0x20
+#define MAP_FAILED      ((void*) -1)
+
+#define MS_ASYNC        0x01
+#define MS_SYNC         0x02
+#define MS_INVALIDATE   0x04
+
+#define MADV_NORMAL     0x00
+#define MADV_RANDOM     0x01
+#define MADV_SEQUENTIAL 0x02
+#define MADV_WILLNEED   0x03
+#define MADV_DONTNEED   0x04
+
+inline void* mmap(void* addr, size_t length, int prot, int flags, int fd, size_t offset, LPCSTR name) {
+    if (prot & ~(PROT_READ | PROT_WRITE | PROT_EXEC))
+        return MAP_FAILED;
+    if (fd == -1) {
+        if (!(flags & MAP_ANONYMOUS) || offset)
+            return MAP_FAILED;
+    } else if (flags & MAP_ANONYMOUS)
+        return MAP_FAILED;
+
+    DWORD protect;
+    if (prot & PROT_WRITE) {
+        if (prot & PROT_EXEC)
+            protect = PAGE_EXECUTE_READWRITE;
+        else
+            protect = PAGE_READWRITE;
+    } else if (prot & PROT_EXEC) {
+        if (prot & PROT_READ)
+            protect = PAGE_EXECUTE_READ;
+        else
+            protect = PAGE_EXECUTE;
+    } else
+        protect = PAGE_READONLY;
+
+    size_t end = length + offset;
+
+#if _WIN64
+    const DWORD dwEndLow = DWORD(end & 0xFFFFFFFFL);
+    const DWORD dwEndHigh = DWORD((end >> 32) & 0xFFFFFFFFL);
+    const DWORD dwOffsetLow = DWORD(offset & 0xFFFFFFFFL);
+    const DWORD dwOffsetHigh = DWORD((offset >> 32) & 0xFFFFFFFFL);
+#else
+    const DWORD dwEndLow = DWORD(end);
+    const DWORD dwEndHigh = DWORD(0);
+    const DWORD dwOffsetLow = DWORD(offset);
+    const DWORD dwOffsetHigh = DWORD(0);
+#endif
+
+    HANDLE h = (fd != -1) ? HANDLE(uv_get_osfhandle(fd)) : INVALID_HANDLE_VALUE;
+    HANDLE fm = CreateFileMapping(h, nullptr, protect, dwEndHigh, dwEndLow, name);
+    if (fm == nullptr)
+        return MAP_FAILED;
+
+    DWORD dwDesiredAccess;
+    if (prot & PROT_WRITE)
+        dwDesiredAccess = FILE_MAP_WRITE;
+    else
+        dwDesiredAccess = FILE_MAP_READ;
+    if (prot & PROT_EXEC)
+        dwDesiredAccess |= FILE_MAP_EXECUTE;
+    if (flags & MAP_PRIVATE)
+        dwDesiredAccess |= FILE_MAP_COPY;
+
+    void *map = MapViewOfFile(fm, dwDesiredAccess, dwOffsetHigh, dwOffsetLow, length);
+    CloseHandle(fm);
+
+    return (map != nullptr) ? map : MAP_FAILED;
+}
+
+inline int munmap(void *addr, size_t length) {
+    if (UnmapViewOfFile(addr))
+        return 0;
+
+    errno = GetLastError();
+    return -1;
+}
+
+inline int msync(void *addr, size_t length, int flags) {
+    if (FlushViewOfFile(addr, length))
+        return 0;
+
+    errno = GetLastError();
+    return -1;
+}
+
+inline int madvise(void *addr, size_t length, int advice) {
+    return 0;   // Unsupported on Windows
+}
+
+inline int mincore(void *addr, size_t length, unsigned char *vec) {
+    errno = ENOSYS;
+    return -1;
+}

package/src/mmap-io.cc

@@ -0,0 +1,340 @@
+/*
+    Licensed under The MIT License (MIT)
+    You will find the full license legal mumbo jumbo in file "LICENSE"
+
+    Copyright (c) 2015 - 2018 Oscar Campbell
+
+    Inspired by Ben Noordhuis module node-mmap - which does the same thing for older node
+    versions, sans advise and sync.
+*/
+#include <nan.h>
+#include <errno.h>
+#include <string>
+
+#ifdef _WIN32
+#include <windows.h>
+#include "mman.h"
+#else
+#include <unistd.h>
+#include <sys/mman.h>
+#endif
+
+using namespace v8;
+
+// Just a bit more clear as to intent
+#define JS_FN(a) NAN_METHOD(a)
+
+// This lib is one of those pieces of code where clarity is better then puny
+// micro opts (in comparison to the massive blocking that will occur when the
+// data is first read from disk) Since casting `size` to `void*` feels a little
+// "out there" considering that `void *` may be 32b or 64b (or, I dunno, 47b on
+// some quant particle system), we throw this struct in.
+struct MMap {
+    MMap(char *data, size_t size) : data(data), size(size) {}
+    char *data = nullptr;
+    size_t size = 0;
+};
+
+void do_mmap_cleanup(char *data, void *hint) {
+    auto map_info = static_cast<MMap*>(hint);
+    munmap(data, map_info->size);
+    delete map_info;
+}
+
+inline int do_mmap_advice(char *addr, size_t length, int advise) {
+    return madvise(static_cast<void*>(addr), length, advise);
+}
+
+// Make it simpler the next time V8 breaks API's and such with a wrapper fn.
+template <typename T, typename VT>
+inline auto get_v(VT v8_value) -> T {
+    return Nan::To<T>(v8_value).FromJust();
+}
+
+// Make it simpler the next time V8 breaks API's and such with a wrapper fn.
+template <typename T, typename VT>
+inline auto get_v(VT v8_value, T default_value) -> T {
+    return Nan::To<T>(v8_value).FromMaybe(default_value);
+}
+
+template <typename VT>
+inline auto get_obj(VT v8_obj) -> Local<Object> {
+    return Nan::To<Object>(v8_obj).ToLocalChecked();
+}
+
+JS_FN(mmap_map) {
+    Nan::HandleScope();
+
+    if (info.Length() < 4 && info.Length() > 7) {
+        return Nan::ThrowError(
+            "map() takes 4, 5, 6 or 7 arguments: (size :int, protection :int, flags :int, fd :int [, offset :int [, advise :int [, name :string ]])."
+        );
+    }
+
+    if (!info[0]->IsNumber()) {
+        return Nan::ThrowError("mmap: size (arg[0]) must be an integer");
+    }
+    if (!info[1]->IsNumber()) {
+        return Nan::ThrowError("mmap: protection_flags (arg[1]) must be an integer");
+    }
+    if (!info[2]->IsNumber()) {
+        return Nan::ThrowError("mmap: flags (arg[2]) must be an integer");
+    }
+    if (!info[3]->IsNumber()) {
+        return Nan::ThrowError("mmap: fd (arg[3]) must be an integer (a file descriptor)");
+    }
+    // offset and advise are optional.
+
+    constexpr void *hinted_address  = nullptr;
+    const size_t    size            = static_cast<size_t>(get_v<int64_t>(info[0]));
+    const int       protection      = get_v<int>(info[1]);
+    const int       flags           = get_v<int>(info[2]);
+    const int       fd              = get_v<int>(info[3]);
+    const size_t    offset          = static_cast<size_t>(get_v<int64_t>(info[4], 0));
+    const int       advise          = get_v<int>(info[5], 0);
+
+#ifdef _WIN32
+    char* nameData = nullptr;
+
+    if (info.Length() > 6) {
+      Local<Object> nameBuf = get_obj(info[6]);
+      nameData = node::Buffer::Data(nameBuf);
+    }
+
+    char* data = static_cast<char*>( mmap( hinted_address, size, protection, flags, fd, offset, nameData) );
+#else
+    char* data = static_cast<char*>( mmap( hinted_address, size, protection, flags, fd, offset) );
+#endif
+
+    if (data == MAP_FAILED) {
+        return Nan::ThrowError((std::string("mmap failed, ") + std::to_string(errno)).c_str());
+    }
+    else {
+        if (advise != 0) {
+            auto ret = do_mmap_advice(data, size, advise);
+            if (ret) {
+                return Nan::ThrowError((std::string("madvise() failed, ") + std::to_string(errno)).c_str());
+            }
+        }
+
+        auto map_info = new MMap(data, size);
+        Nan::MaybeLocal<Object> buf = node::Buffer::New(
+            v8::Isolate::GetCurrent(), data, size, do_mmap_cleanup, static_cast<void*>(map_info));
+        if (buf.IsEmpty()) {
+            return Nan::ThrowError(std::string("couldn't allocate Node Buffer()").c_str());
+        } else {
+            info.GetReturnValue().Set(buf.ToLocalChecked());
+        }
+    }
+}
+
+JS_FN(mmap_advise) {
+    Nan::HandleScope();
+
+    if (info.Length() != 2 && info.Length() != 4) {
+        return Nan::ThrowError(
+            "advise() takes 2 or 4 arguments: (buffer :Buffer, advise :int) | (buffer :Buffer, offset :int, length :int, advise :int)."
+        );
+    }
+    if (!info[0]->IsObject())    return Nan::ThrowError("advice(): buffer (arg[0]) must be a Buffer");
+    if (!info[1]->IsNumber())    return Nan::ThrowError("advice(): (arg[1]) must be an integer");
+
+    Local<Object> buf     = get_obj(info[0]); // info[0]->ToObject(); // get_v<Local<Object>>(info[0]);
+    char *data = node::Buffer::Data(buf);
+    size_t size    = node::Buffer::Length(buf);
+
+    int ret = ([&]() -> int {
+        if (info.Length() == 2) {
+            int advise = get_v<int>(info[1], 0);
+            return do_mmap_advice(data, size, advise);
+        }
+        else {
+            size_t offset = get_v<int64_t>(info[1], 0);
+            size_t length = get_v<int64_t>(info[2], 0);
+            int advise = get_v<int>(info[3], 0);
+            return do_mmap_advice(data + offset, length, advise);
+        }
+    })();
+
+    if (ret) {
+        return Nan::ThrowError((std::string("madvise() failed, ") + std::to_string(errno)).c_str());
+    }
+
+    //Nan::ReturnUndefined();
+}
+
+JS_FN(mmap_incore) {
+    Nan::HandleScope();
+
+    if (info.Length() != 1) {
+        return Nan::ThrowError(
+            "incore() takes 1 argument: (buffer :Buffer) ."
+        );
+    }
+
+    if (!info[0]->IsObject())    return Nan::ThrowError("advice(): buffer (arg[0]) must be a Buffer");
+
+    Local<Object> buf = get_obj(info[0]); // info[0]->ToObject(); // get_v<Local<Object>>(info[0]);
+    char *data = node::Buffer::Data(buf);
+    size_t size = node::Buffer::Length(buf);
+
+#ifdef _WIN32
+    SYSTEM_INFO sysinfo;
+    GetSystemInfo(&sysinfo);
+    size_t          page_size = sysinfo.dwPageSize;
+#else
+    size_t          page_size = sysconf(_SC_PAGESIZE);
+#endif
+
+    size_t          needed_bytes = (size+page_size-1) / page_size;
+    size_t          pages = size / page_size;
+
+#ifdef __APPLE__
+    char *result_data = static_cast<char *>(malloc(needed_bytes));
+#else
+    unsigned char *result_data = static_cast<unsigned char *>(malloc(needed_bytes));
+#endif
+
+    if (size % page_size > 0) {
+        pages++;
+    }
+
+    int ret = mincore(data, size, result_data);
+
+    if (ret) {
+        free(result_data);
+        if (errno == ENOSYS) {
+            return Nan::ThrowError("mincore() not implemented");
+        } else {
+            return Nan::ThrowError((std::string("mincore() failed, ") + std::to_string(errno)).c_str());
+        }
+    }
+
+    // Now we want to check all of the pages
+    uint32_t pages_mapped = 0;
+    uint32_t pages_unmapped = 0;
+
+    for(size_t i = 0; i < pages; i++) {
+        if(!(result_data[i] & 0x1)) {
+            pages_unmapped++;
+        } else {
+            pages_mapped++;
+        }
+    }
+
+    free(result_data);
+
+    v8::Local<v8::Array> arr = Nan::New<v8::Array>(2);
+    Nan::Set(arr, 0, Nan::New(pages_unmapped));
+    Nan::Set(arr, 1, Nan::New(pages_mapped));
+    info.GetReturnValue().Set(arr);
+}
+
+JS_FN(mmap_sync_lib_private_) {
+    Nan::HandleScope();
+
+    // I barfed at the thought of implementing all variants of info-combos in
+    // C++, so the arg-shuffling and checking is done in a ES wrapper function
+    // - see "mmap-io.ts"
+    if (info.Length() != 5) {
+        return Nan::ThrowError(
+            "sync() takes 5 arguments: (buffer :Buffer, offset :int, length :int, do_blocking_sync :bool, invalidate_pages_and_signal_refresh_to_consumers :bool)."
+        );
+    }
+
+    if (!info[0]->IsObject())    return Nan::ThrowError("sync(): buffer (arg[0]) must be a Buffer");
+
+    Local<Object> buf = get_obj(info[0]); // info[0]->ToObject(); // get_v<Local<Object>>(info[0]);
+    char *data = node::Buffer::Data(buf);
+
+    size_t offset = get_v<int64_t>(info[1], 0);
+    size_t length = get_v<int64_t>(info[2], 0);
+    bool blocking_sync = get_v<bool>(info[3], false);
+    bool invalidate = get_v<bool>(info[4], false);
+    int flags = ( (blocking_sync ? MS_SYNC : MS_ASYNC) | (invalidate ? MS_INVALIDATE : 0) );
+
+    int ret = msync(data + offset, length, flags);
+
+    if (ret) {
+        return Nan::ThrowError((std::string("msync() failed, ") + std::to_string(errno)).c_str());
+    }
+    //Nan::ReturnUndefined();
+}
+
+NAN_MODULE_INIT(Init) {
+    auto exports = target;
+
+    constexpr auto std_property_attrs = static_cast<PropertyAttribute>(
+        ReadOnly | DontDelete
+    );
+
+    using JsFnType = decltype(mmap_map);
+
+    auto set_int_prop = [&](const char *key, int val) -> void {
+        Nan::DefineOwnProperty(
+            exports,
+            Nan::New(key).ToLocalChecked(),
+            Nan::New(val),
+            std_property_attrs
+        );
+    };
+
+    auto set_fn_prop = [&](const char *key, JsFnType fn) -> void {
+        Nan::DefineOwnProperty(
+            exports,
+            Nan::New<v8::String>(key).ToLocalChecked(),
+            Nan::GetFunction(Nan::New<FunctionTemplate>(fn)).ToLocalChecked(),
+            std_property_attrs
+        );
+    };
+
+    set_int_prop("PROT_READ", PROT_READ);
+    set_int_prop("PROT_WRITE", PROT_WRITE);
+    set_int_prop("PROT_EXEC", PROT_EXEC);
+    set_int_prop("PROT_NONE", PROT_NONE);
+
+    set_int_prop("MAP_SHARED", MAP_SHARED);
+    set_int_prop("MAP_ANONYMOUS", MAP_ANONYMOUS);
+    set_int_prop("MAP_PRIVATE", MAP_PRIVATE);
+
+#ifdef MAP_NONBLOCK
+    set_int_prop("MAP_NONBLOCK", MAP_NONBLOCK);
+#endif
+
+#ifdef MAP_POPULATE
+    set_int_prop("MAP_POPULATE", MAP_POPULATE);
+#endif
+
+    set_int_prop("MADV_NORMAL", MADV_NORMAL);
+    set_int_prop("MADV_RANDOM", MADV_RANDOM);
+    set_int_prop("MADV_SEQUENTIAL", MADV_SEQUENTIAL);
+    set_int_prop("MADV_WILLNEED", MADV_WILLNEED);
+    set_int_prop("MADV_DONTNEED", MADV_DONTNEED);
+
+    //set_int_prop("MS_ASYNC", MS_ASYNC);
+    //set_int_prop("MS_SYNC", MS_SYNC);
+    //set_int_prop("MS_INVALIDATE", MS_INVALIDATE);
+
+#ifdef _WIN32
+    SYSTEM_INFO sysinfo;
+    GetSystemInfo(&sysinfo);
+    set_int_prop("PAGESIZE", sysinfo.dwPageSize);
+#else
+    set_int_prop("PAGESIZE", sysconf(_SC_PAGESIZE));
+#endif
+
+    set_fn_prop("map", mmap_map);
+    set_fn_prop("advise", mmap_advise);
+    set_fn_prop("incore", mmap_incore);
+
+    // This one is wrapped by a JS-function and deleted from obj to hide from user
+    Nan::DefineOwnProperty(
+        exports,
+        Nan::New<v8::String>("sync_lib_private__").ToLocalChecked(),
+        Nan::GetFunction(Nan::New<FunctionTemplate>(mmap_sync_lib_private_)).ToLocalChecked(),
+        static_cast<PropertyAttribute>(0)
+    );
+
+}
+
+NAN_MODULE_WORKER_ENABLED(mmap_io, Init);

package/src/mmap-io.ts

@@ -0,0 +1,132 @@
+const binary = require('@mapbox/node-pre-gyp');
+const path = require('path');
+const binding_path = binary.find(path.resolve(path.join(__dirname,'../package.json')));
+const mmap_lib_raw_ = require(binding_path);
+
+type FileDescriptor = number
+
+type MapProtectionFlags =
+    | MmapIo["PROT_NONE"] // 0
+    | MmapIo["PROT_READ"] // 1
+    | MmapIo["PROT_WRITE"] // 2
+    | MmapIo["PROT_EXEC"] // 4
+    | 3 // R+W
+    | 5 // R+X
+    | 6 // W+X
+    | 7 // R+W+X
+
+// making `map` a wrapper around the C++ `map`-implementation and allowing an
+// array of flags would be clean, perfectly literally typed, and the dirtier
+// binary-or can be done in the wrapper.
+//
+// type MapProtectionFlagsList = Array<
+//     | MmapIo["PROT_NONE"]
+//     | MmapIo["PROT_READ"]
+//     | MmapIo["PROT_WRITE"]
+//     | MmapIo["PROT_EXEC"]
+// >
+
+type MapFlags =
+    | MmapIo["MAP_SHARED"]
+    | MmapIo["MAP_PRIVATE"]
+    | MmapIo["MAP_ANONYMOUS"]
+    | MmapIo["MAP_POPULATE"]
+    | MmapIo["MAP_NONBLOCK"]
+    | number
+
+type MapAdvise =
+    | MmapIo["MADV_NORMAL"]
+    | MmapIo["MADV_RANDOM"]
+    | MmapIo["MADV_SEQUENTIAL"]
+    | MmapIo["MADV_WILLNEED"]
+    | MmapIo["MADV_DONTNEED"]
+
+type MmapIo = {
+    map(
+        size: number,
+        protection: MapProtectionFlags,
+        flags: MapFlags,
+        fd: FileDescriptor,
+        offset?: number,
+        advise?: MapAdvise,
+        name?: Buffer
+    ): Buffer
+
+    advise(
+        buffer: Buffer,
+        offset: number,
+        length: number,
+        advise: MapAdvise
+    ): void
+    advise(buffer: Buffer, advise: MapAdvise): void
+
+    /// Returns tuple of [ unmapped-pages-count, mapped-pages-count ]
+    incore(buffer: Buffer): [number, number]
+
+    sync(
+        buffer: Buffer,
+        offset?: number,
+        size?: number,
+        blocking_sync?: boolean,
+        invalidate_pages?: boolean
+    ): void
+
+    sync(
+        buffer: Buffer,
+        blocking_sync: boolean,
+        invalidate_pages?: boolean
+    ): void
+
+    readonly PROT_READ: 1
+    readonly PROT_WRITE: 2
+    readonly PROT_EXEC: 4
+    readonly PROT_NONE: 0
+
+    readonly MAP_SHARED: 1
+    readonly MAP_PRIVATE: 2
+    readonly MAP_ANONYMOUS: 32
+    readonly MAP_POPULATE: 32768
+    readonly MAP_NONBLOCK: 65536
+
+    readonly MADV_NORMAL: 0
+    readonly MADV_RANDOM: 1
+    readonly MADV_SEQUENTIAL: 2
+    readonly MADV_WILLNEED: 3
+    readonly MADV_DONTNEED: 4
+
+    readonly PAGESIZE: number
+}
+
+// snatch the raw C++-sync func
+const raw_sync_fn_ = mmap_lib_raw_.sync_lib_private__
+
+// Hide the original C++11 func from users
+delete mmap_lib_raw_.sync_lib_private__
+
+// Take care of all the param juggling here instead of in C++ code, by making
+// some overloads, and doing some argument defaults
+mmap_lib_raw_.sync = function(
+    buf: Buffer,
+    par_a?: any,
+    par_b?: any,
+    par_c?: any,
+    par_d?: any
+): void {
+    if (typeof par_a === "boolean") {
+        raw_sync_fn_(buf, 0, buf.length, par_a, par_b || false)
+    } else {
+        raw_sync_fn_(
+            buf,
+            par_a || 0,
+            par_b || buf.length,
+            par_c || false,
+            par_d || false
+        )
+    }
+}
+
+// mmap_lib_raw_.sync = sync_
+
+const mmap = mmap_lib_raw_ as MmapIo
+module.exports = mmap
+export default mmap

package/src/test.types.ts

@@ -0,0 +1,22 @@
+import mmap from "./mmap-io"
+import fs from "fs"
+
+const fd = fs.openSync(__filename, "r+")
+
+/**
+ * Writing, for instance `4` instead of ie `2` (MADV_SEQUENTIAL), here, will
+ * give an error already while typing (provided language-server is setup)
+ * because of the specific types
+ *
+ * A problem arise with the traditional dirty technique of binary-or, widening
+ * the type from literal to number-field
+ */
+
+mmap.map(
+    100,
+    (mmap.PROT_EXEC | mmap.PROT_READ) as 5,
+    mmap.MAP_SHARED,
+    fd,
+    0,
+    mmap.MADV_SEQUENTIAL
+)