koffi 2.3.0-beta.2 → 2.3.1

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 ## Version history
 
+### Koffi 2.3
+
+#### Koffi 2.3.1
+
+**Main changes:**
+
+- Error out when trying to use ambiguous `void *` arguments (input and/or output)
+- Adjust TypeScript definitions ([@insraq](https://github.com/insraq))
+- Fix possible crash when parsing invalid prototype
+
+#### 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-buffers)
+- 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*
 
@@ -177,7 +179,7 @@ There is also an optional ending `length` argument that you can use in two cases
 In Koffi 2.2 and earlier versions, the length argument is only used to decode strings and is ignored otherwise.
 ```
 
-## Asynchronous callbacks
+### Asynchronous callbacks
 
 *New in Koffi 2.2.2*
 

package/doc/calls.md

@@ -159,7 +159,7 @@ console.log(out[0]);
 
 ## Polymorphic parameters
 
-### Input parameters
+### Input polymorphism
 
 *New in Koffi 2.1*
 
@@ -221,7 +221,7 @@ let hdr = {};
 console.log('PNG header:', hdr);
 ```
 
-### Output parameters
+### Output buffers
 
 *New in Koffi 2.3*
 
@@ -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
 
@@ -287,7 +287,6 @@ The following example illustrates the use of a disposable type derived from *str
 const koffi = require('koffi');
 const lib = koffi.load('libc.so.6');
 
-// You can also use: const strdup = lib.func('const char *! strdup(const char *str)')
 const HeapStr = koffi.disposable('str');
 const strdup = lib.cdecl('strdup', HeapStr, ['str']);
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "koffi",
-    "version": "2.3.0-beta.2",
-    "stable": "2.2.5",
+    "version": "2.3.1",
+    "stable": "2.3.1",
     "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

@@ -909,6 +909,12 @@ bool CallData::PushPointer(Napi::Value value, const TypeInfo *type, int directio
             uint8_t *ptr = nullptr;
 
             if (value.IsArray()) {
+                if (RG_UNLIKELY(!type->ref.type->size)) {
+                    ThrowError<Napi::TypeError>(env, "Cannot pass %1 value to void *, use koffi.as()",
+                                                type->ref.type != instance->void_type ? "opaque" : "ambiguous");
+                    return false;
+                }
+
                 Napi::Array array = value.As<Napi::Array>();
 
                 Size len = (Size)array.Length();
@@ -936,6 +942,12 @@ bool CallData::PushPointer(Napi::Value value, const TypeInfo *type, int directio
                     directions = 1;
                 }
             } else if (RG_LIKELY(type->ref.type->primitive == PrimitiveKind::Record)) {
+                if (RG_UNLIKELY(!type->ref.type->size)) {
+                    ThrowError<Napi::TypeError>(env, "Cannot pass %1 value to void *, use koffi.as()",
+                                                type->ref.type != instance->void_type ? "opaque" : "ambiguous");
+                    return false;
+                }
+
                 Napi::Object obj = value.As<Napi::Object>();
                 RG_ASSERT(IsObject(value));
 

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

@@ -0,0 +1,95 @@
+// 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: IKoffiCType, 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: any, 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;
+
+    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: any, type: TypeSpec): any;
+    export function decode(value: any, type: TypeSpec, len: number): any;
+    export function decode(value: any, offset: number, type: TypeSpec): any;
+    export function decode(value: any, offset: number, type: TypeSpec, len: number): any;
+
+    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(): Record<string, unknown>;
+    export function config(cfg: Record<string, unknown>): Record<string, unknown>;
+}

package/src/koffi/src/parser.cc

@@ -152,6 +152,7 @@ const TypeInfo *PrototypeParser::ParseType()
         offset++;
     }
     offset += (offset < tokens.len && tokens[offset] == "!");
+    offset = std::min(tokens.len - 1, offset);
 
     while (offset >= start) {
         Span<const char> str = MakeSpan(tokens[start].ptr, tokens[offset].end() - tokens[start].ptr);