koffi 2.3.0-beta.2 → 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*
 
@@ -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

@@ -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.2",
-    "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/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({}): {}
+}