koffi 2.3.0-beta.1 → 2.3.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## Version history
 
+### Koffi 2.3
+
+#### Koffi 2.3.0
+
+**Main changes:**
+
+- Allow buffers (TypedArray or ArrayBuffer) values for input and/or output pointer arguments (for polymorphic arguments)
+- Support opaque buffers (TypedArray or ArrayBuffer) values in `koffi.decode()` to [decode output buffers](calls.md#output-parameters)
+- Decode non-string types as arrays when an [explicit length is passed to koffi.decode()](callbacks.md#pointer-arguments)
+
+**Other changes:**
+
+- Drop TypedArray type check for array and pointer values (only the size matters)
+- Allow ArrayBuffer everywhere TypedArray is supported
+- Add TypeScript definition for Koffi ([@insraq](https://github.com/insraq))
+- Improve documentation about opaque and polymorphic structs
+- Improve documentation for `koffi.decode()`
+- Reduce NPM package size (from 100 MB to 25 MB) by removing test code and dependencies
+
 ### Koffi 2.2
 
 #### Koffi 2.2.5

package/doc/callbacks.md

@@ -134,7 +134,9 @@ let cb1 = koffi.register(store.get, 'IntCallback *'); // If a C function calls c
 let cb2 = koffi.register(store, store.get, 'IntCallback *'); // However in this case, this will match the store object
 ```
 
-## Pointer arguments
+## Special considerations
+
+### Decoding pointer arguments
 
 *New in Koffi 2.2, changed in Koffi 2.3*
 
@@ -173,7 +175,11 @@ There is also an optional ending `length` argument that you can use in two cases
 - Use it to give the number of bytes to decode in non-NUL terminated strings: `koffi.decode(value, 'char *', 5)`
 - Decode consecutive values into an array. For example, here is how you can decode an array with 3 float values: `koffi.decode(value, 'float', 3)`. This is equivalent to `koffi.decode(value, koffi.array('float', 3))`.
 
-## Asynchronous callbacks
+```{note}
+In Koffi 2.2 and earlier versions, the length argument is only used to decode strings and is ignored otherwise.
+```
+
+### Asynchronous callbacks
 
 *New in Koffi 2.2.2*
 

package/doc/calls.md

@@ -261,7 +261,7 @@ console.log(vec1); // { x: 3, y: 2, z: 1 }
 console.log(vec2); // { x: 1, y: 2, z: 3 }
 ```
 
-See [pointer arguments](callbacks.md#pointer-arguments) for more information about the decode function.
+See [pointer arguments](callbacks.md#decoding-pointer-arguments) for more information about the decode function.
 
 ## Heap-allocated values
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "koffi",
-    "version": "2.3.0-beta.1",
-    "stable": "2.2.5",
+    "version": "2.3.0",
+    "stable": "2.3.0",
     "description": "Fast and simple C FFI (foreign function interface) for Node.js",
     "keywords": [
         "foreign",
@@ -19,6 +19,7 @@
     "homepage": "https://koffi.dev/",
     "author": "Niels Martignène <niels.martignene@protonmail.com>",
     "main": "src/koffi/src/index.js",
+    "types": "src/koffi/src/index.d.ts",
     "scripts": {
         "install": "cnoke --prebuild -d src/koffi"
     },

package/src/koffi/src/call.cc

@@ -923,15 +923,17 @@ bool CallData::PushPointer(Napi::Value value, const TypeInfo *type, int directio
                     memset_safe(ptr, 0, size);
                 }
             } else if (IsRawBuffer(value)) {
-                Span<const uint8_t> buffer = GetRawBuffer(value);
+                Span<uint8_t> buffer = GetRawBuffer(value);
 
-                ptr = AllocHeap(buffer.len, 16);
+                if (directions == 1) {
+                    ptr = AllocHeap(buffer.len, 16);
 
-                if (directions & 1) {
                     if (!PushBuffer(buffer, buffer.len, type, ptr))
                         return false;
                 } else {
-                    memset_safe(ptr, 0, (size_t)buffer.len);
+                    // Fast no-copy path
+                    ptr = buffer.ptr;
+                    directions = 1;
                 }
             } else if (RG_LIKELY(type->ref.type->primitive == PrimitiveKind::Record)) {
                 Napi::Object obj = value.As<Napi::Object>();

package/src/koffi/src/index.d.ts

@@ -0,0 +1,96 @@
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with this program. If not, see https://www.gnu.org/licenses/.
+
+declare module 'koffi' {
+    export function load(path: string): IKoffiLib;
+
+    interface IKoffiCType { __brand: 'IKoffiCType' }
+    interface IKoffiPointerCast { __brand: 'IKoffiPointerCast' }
+    interface IKoffiRegisteredCallback { __brand: 'IKoffiRegisteredCallback' }
+
+    type TypeSpec = string | IKoffiCType;
+    type TypeSpecWithAlignment = TypeSpec | [number, TypeSpec];
+    type TypeInfo = {
+        name: string,
+        primitive: string,
+        size: number,
+        alignment: number,
+        length: number,
+        ref: IKoffiCType,
+        members: Record<string, { name: string, type: {}, offset: number }>
+    };
+    type KoffiFunction = Function | { async: Function };
+
+    export interface IKoffiLib {
+        func(definition: string): KoffiFunction;
+        func(name: string, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
+
+        cdecl(definition: string): KoffiFunction;
+        cdecl(name: string, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
+
+        stdcall(definition: string): KoffiFunction;
+        stdcall(name: string, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
+
+        fastcall(definition: string): KoffiFunction;
+        fastcall(name: string, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
+
+        thiscall(definition: string): KoffiFunction;
+        thiscall(name: string, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
+    }
+
+    export function struct(name: string, def: Record<string, TypeSpecWithAlignment>): IKoffiCType;
+    export function struct(def: Record<string, TypeSpecWithAlignment>): IKoffiCType;
+
+    export function pack(name: string, def: Record<string, TypeSpecWithAlignment>): IKoffiCType;
+    export function pack(def: Record<string, TypeSpecWithAlignment>): IKoffiCType;
+
+    export function opaque(name: string): IKoffiCType;
+    export function opaque(): IKoffiCType;
+
+    export function pointer(value: TypeSpec): IKoffiCType;
+    export function pointer(value: TypeSpec, asteriskCount: number): IKoffiCType;
+    export function pointer(name: string, value: TypeSpec, asteriskCount: number): IKoffiCType;
+
+    export function out(value: TypeSpec): IKoffiCType;
+    export function inout(value: TypeSpec): IKoffiCType;
+
+    export function as(value: {}, type: TypeSpec): IKoffiPointerCast;
+
+    export function disposable(type: TypeSpec): IKoffiCType;
+    export function disposable(name: string, type: TypeSpec): IKoffiCType;
+    export function disposable(name: string, type: TypeSpec, freeFunction: Function): IKoffiCType;
+
+    export function callback(definition: string): IKoffiCType;
+    export function callback(name: string, result: TypeSpec, arguments: TypeSpec[]): IKoffiCType;
+
+    interface IKoffiRegisteredCallback { __brand: 'IKoffiRegisteredCallback' }
+    export function register(callback: Function, type: TypeSpec): IKoffiRegisteredCallback;
+    export function register(thisValue: any, callback: Function, type: TypeSpec): IKoffiRegisteredCallback;
+    export function unregister(callback: IKoffiRegisteredCallback): void;
+
+    export function decode(value: {}, type: TypeSpec): {};
+    export function decode(value: {}, type: TypeSpec, len: number): {};
+    export function decode(value: {}, offset: number, type: TypeSpec): {};
+    export function decode(value: {}, offset: number, type: TypeSpec, len: number): {};
+
+    export function sizeof(type: TypeSpec): number;
+    export function alignof(type: TypeSpec): number;
+    export function offsetof(type: TypeSpec): number;
+    export function resolve(type: TypeSpec): IKoffiCType;
+    export function introspect(type: TypeSpec): TypeInfo;
+
+    export function alias(name: string, type: TypeSpec): IKoffiCType;
+
+    export function config(): {}
+    export function config({}): {}
+}