knitting 0.1.54 → 0.1.55

package/map.md

@@ -18,7 +18,7 @@ The core flow is:
 
 - `knitting.ts`: Main package entry. Re-exports `createPool`, `task`,
   `importTask`, `isMain`, `Envelope`, and `workerMainLoop`.
-- `process-shared-buffer.ts`: Secondary public export for process-shared-buffer
+- `shared-memory.ts`: Secondary public export for process-safe shared-memory
   helpers.
 - `unsafe.ts`: Public export for experimental lower-level capabilities such as
   `BufferReference`.
@@ -34,11 +34,11 @@ The core flow is:
 
 ## Build And Scripts
 
-- `build.ts`: Bundles `knitting.ts` to `out/` with Bun for a Node ESM target.
-- `tsconfig.npm.json`: TypeScript config for the npm release build. Emits
-  `.js` and `.d.ts` files beside the source tree.
-- `scripts/rewrite-declaration-imports.mjs`: Post-processes emitted `.d.ts`
-  files so declaration imports point at `.js` files for npm consumers.
+- `build.ts`: Bundles each public entry to one root `.js` file with Bun for a
+  Node ESM target.
+- `tsconfig.npm.json`: TypeScript config used by npm declaration bundling.
+- `scripts/build-declarations.mjs`: Bundles each public entry to one root
+  `.d.ts` file for npm consumers.
 - `scripts/build-native-addons.ts`: Compiles the native Node addons into
   `build/Release/` on Linux, macOS, and Windows. It finds Node headers/libs,
   splits user flags, builds the shared-memory and futex addons, and emits the
@@ -309,12 +309,9 @@ The core flow is:
 
 - `build/Release/*.node`: Native addon output produced by
   `scripts/build-native-addons.ts`.
-- `out/`: Bundled output produced by `build.ts`.
-- `dest/`: Scratch output used by the `build:node` package script.
-- `knitting.js`, `knitting.d.ts`, `process-shared-buffer.js`,
-  `process-shared-buffer.d.ts`, and `src/**/*.js` / `src/**/*.d.ts`: npm
-  release build artifacts produced by `tsconfig.npm.json`.
+- `knitting.js`, `knitting.d.ts`, `shared-memory.js`, `shared-memory.d.ts`,
+  `unsafe.js`, `unsafe.d.ts`, `utils.js`, and `utils.d.ts`: npm release build
+  artifacts produced by `build.ts` and `scripts/build-declarations.mjs`.
 - `results/`: Benchmark output produced by `run.sh`.
 - `log/`, `logs`, and `*.log`: Local runtime/log output.
 - `node_modules/`: Installed dependencies. Not part of the source map.
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knitting",
-  "version": "0.1.54",
+  "version": "0.1.55",
   "description": "Shared-memory IPC runtime for Node.js, Deno, and Bun.",
   "license": "Apache-2.0",
   "repository": {
@@ -20,9 +20,9 @@
       "types": "./knitting.d.ts",
       "default": "./knitting.js"
     },
-    "./process-shared-buffer": {
-      "types": "./process-shared-buffer.d.ts",
-      "default": "./process-shared-buffer.js"
+    "./shared-memory": {
+      "types": "./shared-memory.d.ts",
+      "default": "./shared-memory.js"
     },
     "./unsafe": {
       "types": "./unsafe.d.ts",
@@ -41,24 +41,24 @@
     "prebuilds/**/*.dll",
     "scripts/build-native-addons.ts",
     "src/**/*.cc",
-    "src/**/*.d.ts",
-    "src/**/*.js",
     "knitting.d.ts",
     "knitting.js",
-    "process-shared-buffer.d.ts",
-    "process-shared-buffer.js",
+    "shared-memory.d.ts",
+    "shared-memory.js",
     "unsafe.d.ts",
     "unsafe.js",
     "utils.d.ts",
     "utils.js"
   ],
   "scripts": {
-    "build": "bun run build.ts",
-    "build:npm": "tsc -p tsconfig.npm.json && node scripts/rewrite-declaration-imports.mjs",
+    "build": "bun run build.ts && node scripts/build-declarations.mjs",
+    "build:js": "bun run build.ts",
+    "build:types": "node scripts/build-declarations.mjs",
+    "build:npm": "npm run build",
     "build:native": "bun run scripts/build-native-addons.ts",
-    "build:release": "bun run build:native && bun run build && npm run build:npm",
-    "build:node": "bun build knitting.ts --outdir dest --target node --format esm",
-    "prepack": "npm run build:npm",
+    "build:release": "bun run build:native && npm run build",
+    "build:node": "npm run build:js",
+    "prepack": "npm run build",
     "release:npm": "npm run test:all && npm publish",
     "release:npm:dry-run": "npm publish --dry-run",
     "test": "npm run test:deno",
@@ -84,6 +84,7 @@
     "@types/bun": "latest",
     "@types/deno": "latest",
     "@types/node": "latest",
+    "dts-bundle-generator": "^9.5.1",
     "mitata": "^1.0.34",
     "typescript": "^5.2.0"
   }

package/shared-memory.d.ts

@@ -0,0 +1,155 @@
+type SharedBuffer = SharedArrayBuffer | ArrayBuffer;
+type SharedBufferRegion = {
+	sab: SharedBuffer;
+	byteOffset: number;
+	byteLength: number;
+};
+type ConnectionRuntime = "node" | "deno" | "bun";
+type SharedMemoryBuffer = ArrayBuffer | SharedArrayBuffer;
+type SharedMemoryBufferKind = "shared-array-buffer" | "external-array-buffer";
+type SharedMemoryCreateMode = "anonymous" | "create" | "open";
+type SharedMemoryMapping<Buffer extends SharedMemoryBuffer = SharedMemoryBuffer> = {
+	runtime: ConnectionRuntime;
+	fd: number;
+	name?: string;
+	size: number;
+	byteLength: number;
+	buffer: Buffer;
+	kind: SharedMemoryBufferKind;
+	sab?: SharedArrayBuffer;
+	arrayBuffer?: ArrayBuffer;
+	baseAddressMod64?: number;
+	unsafePointer?: unknown;
+	close?: () => void;
+};
+type CreateSharedMemoryOptions = {
+	size: number;
+	/**
+	 * `anonymous` keeps the current fd-backed private mapping behavior.
+	 * `create` and `open` use a named shared-memory object so independent
+	 * processes can rendezvous by name.
+	 */
+	mode?: SharedMemoryCreateMode;
+	name?: string;
+};
+type MapSharedMemoryOptions = {
+	fd: number;
+	name?: string;
+	size: number;
+	duplicateFd?: boolean;
+};
+type SharedMemoryConnectionPrimitives<Mapping extends SharedMemoryMapping = SharedMemoryMapping> = {
+	runtime: ConnectionRuntime;
+	createSharedMemory: (options: number | CreateSharedMemoryOptions) => Mapping;
+	mapSharedMemory: (options: MapSharedMemoryOptions) => Mapping;
+	unlinkSharedMemory?: (name: string) => boolean;
+};
+type FileDescriptorMetadata = {
+	version: 1;
+	fd: number;
+	name?: string;
+	size: number;
+	byteLength: number;
+	runtime?: ConnectionRuntime;
+	kind?: SharedMemoryMapping["kind"];
+	baseAddressMod64?: number;
+};
+type FileDescriptorMapper = Pick<SharedMemoryConnectionPrimitives, "mapSharedMemory">;
+declare class FileDescriptor {
+	#private;
+	readonly fd: number;
+	readonly name?: string;
+	readonly size: number;
+	readonly byteLength: number;
+	readonly runtime?: ConnectionRuntime;
+	readonly kind?: SharedMemoryMapping["kind"];
+	readonly baseAddressMod64?: number;
+	constructor(metadata: FileDescriptorMetadata, mapping?: SharedMemoryMapping);
+	static fromMapping(mapping: SharedMemoryMapping): FileDescriptor;
+	static fromMetadata(metadata: unknown): FileDescriptor;
+	static parse(serialized: string): FileDescriptor;
+	toMetadata(): FileDescriptorMetadata;
+	toJSON(): FileDescriptorMetadata;
+	stringify(): string;
+	stringifyMetadata(): string;
+	toString(): string;
+	attach(mapping: SharedMemoryMapping): this;
+	get mapping(): SharedMemoryMapping | undefined;
+	map(mapper: FileDescriptorMapper): SharedMemoryMapping;
+	getBuffer(mapper?: FileDescriptorMapper): SharedMemoryBuffer;
+	getSharedArrayBuffer(mapper?: FileDescriptorMapper): SharedArrayBuffer;
+	getSAB(mapper?: FileDescriptorMapper): SharedArrayBuffer;
+}
+export type ProcessSharedBufferMetadata = {
+	version: 1;
+	descriptor: FileDescriptorMetadata;
+	byteOffset: number;
+	byteLength: number;
+};
+export declare const PROCESS_SHARED_BUFFER_BRAND: unique symbol;
+declare const PROCESS_SHARED_BUFFER_NUMERIC_TRANSFER: unique symbol;
+declare const EXTERNAL_PAYLOAD_BRAND: unique symbol;
+type ProcessSharedBufferNumericMetadata = readonly [
+	fd: number,
+	size: number,
+	descriptorByteLength: number,
+	byteOffset: number,
+	byteLength: number,
+	runtime: number,
+	kind: number,
+	baseAddressMod64: number
+];
+export type ProcessSharedBufferRange = {
+	byteOffset?: number;
+	byteLength?: number;
+};
+export type ProcessSharedBufferCreator = Pick<SharedMemoryConnectionPrimitives, "createSharedMemory">;
+export type ProcessSharedBufferMapper = Pick<SharedMemoryConnectionPrimitives, "mapSharedMemory">;
+export type ProcessSharedBufferPrimitives = Pick<SharedMemoryConnectionPrimitives, "createSharedMemory" | "mapSharedMemory"> & {
+	unlinkSharedMemory?: (name: string) => boolean;
+};
+export type ProcessSharedBufferView = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | BigInt64Array | BigUint64Array | Float32Array | Float64Array;
+export type ProcessSharedBufferViewConstructor<View extends ProcessSharedBufferView = ProcessSharedBufferView> = {
+	readonly BYTES_PER_ELEMENT: number;
+	new (buffer: SharedBuffer, byteOffset: number, length: number): View;
+};
+export declare const setDefaultProcessSharedBufferPrimitives: (primitives: ProcessSharedBufferPrimitives | undefined) => void;
+export declare const getDefaultProcessSharedBufferPrimitives: () => ProcessSharedBufferPrimitives;
+/**
+ * Zero-copy shared bytes for process workers.
+ *
+ * Use this when the boundary is a separate process, container, or sandbox.
+ * For thread workers, `SharedArrayBuffer` or `BufferReference` can be cheaper.
+ */
+export declare class ProcessSharedBuffer {
+	readonly [PROCESS_SHARED_BUFFER_BRAND] = true;
+	readonly [EXTERNAL_PAYLOAD_BRAND] = "knitting.processSharedBuffer";
+	readonly descriptor: FileDescriptor;
+	readonly byteOffset: number;
+	readonly byteLength: number;
+	constructor(descriptor: FileDescriptor, range?: ProcessSharedBufferRange);
+	static create(options: number | CreateSharedMemoryOptions, creator?: ProcessSharedBufferCreator): ProcessSharedBuffer;
+	static fromMapping(mapping: SharedMemoryMapping): ProcessSharedBuffer;
+	static fromDescriptor(descriptor: FileDescriptor, range?: ProcessSharedBufferRange): ProcessSharedBuffer;
+	static fromMetadata(metadata: unknown): ProcessSharedBuffer;
+	static parse(serialized: string): ProcessSharedBuffer;
+	static [PROCESS_SHARED_BUFFER_NUMERIC_TRANSFER](metadata: ProcessSharedBufferNumericMetadata): ProcessSharedBuffer;
+	get fd(): number;
+	get size(): number;
+	subbuffer(byteOffset: number, byteLength?: number): ProcessSharedBuffer;
+	getSharedArrayBuffer(mapper?: ProcessSharedBufferMapper): SharedArrayBuffer;
+	getSAB(mapper?: ProcessSharedBufferMapper): SharedArrayBuffer;
+	getBuffer(mapper?: ProcessSharedBufferMapper): SharedBuffer;
+	getRegion(mapper?: ProcessSharedBufferMapper): SharedBufferRegion;
+	view<View extends ProcessSharedBufferView>(constructor: ProcessSharedBufferViewConstructor<View>, mapper?: ProcessSharedBufferMapper): View;
+	bytes(mapper?: ProcessSharedBufferMapper): Uint8Array;
+	dataView(mapper?: ProcessSharedBufferMapper): DataView;
+	toMetadata(): ProcessSharedBufferMetadata;
+	toJSON(): ProcessSharedBufferMetadata;
+	stringify(): string;
+	stringifyMetadata(): string;
+	toString(): string;
+}
+export declare const parseProcessSharedBufferMetadata: (input: unknown) => ProcessSharedBufferMetadata;
+
+export {};