koffi-cream 2.11.0

package/README.md

@@ -0,0 +1,59 @@
+# Koffi-Cream
+
+A lighter packaging of Niels Martignène's excellent [Koffi](https://koffi.dev).
+
+Just `npm install koffi-cream` instead of `koffi` and use it like the real thing:
+
+```ts
+import koffi from 'koffi-cream'
+
+const lib = koffi.lib('some_lib')
+const fn = lib.func('int some_func(int a, int b)')
+// etc.
+```
+
+## The why and the how
+
+Most importantly: **this package is neither a fork nor a patch. It *is* the original Koffi**, only packaged differently to avoid downloading a megalithic[^1] package full of unnecessary files[^2].
+
+`koffi-cream` repackages Koffi using the same strategy as many popular packages in the JavaScript community like `esbuild` or `swc`: by leveraging the `optionalDependencies`, `os`, `cpu` and `libc` properties in `package.json`.
+
+This way, when you install `koffi-cream`, your package manager will only download and install the build that is right for your platform. For example, on Windows AMD/Intel 64 bit, your package manager will install:
+- `koffi-cream` (this package): 3.4 kB compressed / 12.8 kB uncompressed
+- `@septh/koffi-win32-x64`: 455 kB compressed / 2.3 MB uncompressed
+
+**That's 97% off compared to the original Koffi package!**
+
+[^1]: As of 2.11.0, Koffi weights 15 MB compressed and 75 MB uncompressed!
+[^2]: Koffi's package includes 16 natives binaries (of which 15 won't work on your platform), the build tools and the full source code!
+
+## Available packages
+
+`koffi-cream` only offers a subset of Koffi's 16 builds:
+
+* [@septh/koffi-darwin-arm64](https://www.npmjs.com/package/@septh/koffi-darwin-arm64)
+* [@septh/koffi-darwin-x64](https://www.npmjs.com/package/@septh/koffi-darwin-x64)
+* [@septh/koffi-freebsd-arm64](https://www.npmjs.com/package/@septh/koffi-freebsd-arm64)
+* [@septh/koffi-freebsd-x64](https://www.npmjs.com/package/@septh/koffi-freebsd-x64)
+* [@septh/koffi-linux-arm64](https://www.npmjs.com/package/@septh/koffi-linux-arm64)
+* [@septh/koffi-linux-riscv64](https://www.npmjs.com/package/@septh/koffi-linux-riscv64)
+* [@septh/koffi-linux-x64-glibc](https://www.npmjs.com/package/@septh/koffi-linux-x64-glibc)
+* [@septh/koffi-linux-x64-musl](https://www.npmjs.com/package/@septh/koffi-linux-x64-musl)
+* [@septh/koffi-openbsd-x64](https://www.npmjs.com/package/@septh/koffi-openbsd-x64)
+* [@septh/koffi-win32-arm64](https://www.npmjs.com/package/@septh/koffi-win32-arm64)
+* [@septh/koffi-win32-x64](https://www.npmjs.com/package/@septh/koffi-win32-x64)
+
+I do not plan to add other builds, especially not the 32 bit binaries. If you need these, stick with Koffi.
+
+## Version numbering
+
+To make things easy on the user, `koffi-cream`'s version number will always be aligned with Koffi's.
+
+Hence, the first version available of `koffi-cream` is 2.11.0 because that version ships with Koffi 2.11.0.
+
+## Related
+
+- The discussion at https://github.com/Koromix/koffi/issues/201 explains why I decided to create `koffi-cream` myself.
+
+## License
+MIT

package/index.d.ts

@@ -0,0 +1,169 @@
+// Copyright 2023 Niels Martignène <niels.martignene@protonmail.com>
+//
+// 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.
+
+declare module 'koffi-cream' {
+    export function load(path: string | null): IKoffiLib;
+
+    interface IKoffiCType { __brand: 'IKoffiCType' }
+    interface IKoffiPointerCast { __brand: 'IKoffiPointerCast' }
+    interface IKoffiRegisteredCallback { __brand: 'IKoffiRegisteredCallback' }
+
+    type PrimitiveKind = 'Void' | 'Bool' | 'Int8' | 'UInt8' | 'Int16' | 'Int16S' | 'UInt16' | 'UInt16S' |
+                         'Int32' | 'Int32S' | 'UInt32' | 'UInt32S' | 'Int64' | 'Int64S' | 'UInt64' | 'UInt64S' |
+                         'String' | 'String16' | 'Pointer' | 'Record' | 'Union' | 'Array' | 'Float32' | 'Float64' |
+                         'Prototype' | 'Callback';
+    type ArrayHint = 'Array' | 'Typed' | 'String';
+
+    type TypeSpec = string | IKoffiCType;
+    type TypeSpecWithAlignment = TypeSpec | [number, TypeSpec];
+    type TypeInfo = {
+        name: string;
+        primitive: PrimitiveKind;
+        size: number;
+        alignment: number;
+        disposable: boolean;
+        length?: number;
+        hint?: ArrayHint;
+        ref?: IKoffiCType;
+        members?: Record<string, { name: string, type: IKoffiCType, offset: number }>;
+    };
+    type KoffiFunction = {
+        (...args: any[]) : any;
+        async: (...args: any[]) => any;
+        info: {
+            name: string,
+            arguments: IKoffiCType[],
+            result: IKoffiCType
+        };
+    };
+
+    export type KoffiFunc<T extends (...args: any) => any> = T & {
+       async: (...args: [...Parameters<T>, (err: any, result: ReturnType<T>) => void]) => void;
+       info: {
+          name: string;
+          arguments: IKoffiCType[];
+          result: IKoffiCType;
+       };
+    };
+
+    export interface IKoffiLib {
+        func(definition: string): KoffiFunction;
+        func(name: string, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
+        func(convention: string, name: string, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
+
+        /** @deprecated */ cdecl(definition: string): KoffiFunction;
+        /** @deprecated */ cdecl(name: string, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
+        /** @deprecated */ stdcall(definition: string): KoffiFunction;
+        /** @deprecated */ stdcall(name: string, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
+        /** @deprecated */ fastcall(definition: string): KoffiFunction;
+        /** @deprecated */ fastcall(name: string, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
+        /** @deprecated */ thiscall(definition: string): KoffiFunction;
+        /** @deprecated */ thiscall(name: string, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
+
+        symbol(name: string, type: TypeSpec): any;
+
+        unload(): void;
+    }
+
+    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 union(name: string, def: Record<string, TypeSpecWithAlignment>): IKoffiCType;
+    export function union(def: Record<string, TypeSpecWithAlignment>): IKoffiCType;
+
+    export class Union {
+        constructor(type: TypeSpec);
+        [s: string]: any;
+    }
+
+    export function array(ref: TypeSpec, len: number, hint?: ArrayHint | null): IKoffiCType;
+
+    export function opaque(name: string): IKoffiCType;
+    export function opaque(): IKoffiCType;
+    /** @deprecated */ export function handle(name: string): IKoffiCType;
+    /** @deprecated */ export function handle(): IKoffiCType;
+
+    export function pointer(ref: TypeSpec): IKoffiCType;
+    export function pointer(ref: TypeSpec, asteriskCount?: number): IKoffiCType;
+    export function pointer(name: string, ref: TypeSpec, asteriskCount?: number): IKoffiCType;
+
+    export function out(type: TypeSpec): IKoffiCType;
+    export function inout(type: TypeSpec): IKoffiCType;
+
+    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 proto(definition: string): IKoffiCType;
+    export function proto(name: string, result: TypeSpec, arguments: TypeSpec[]): IKoffiCType;
+    export function proto(convention: string, name: string, result: TypeSpec, arguments: TypeSpec[]): IKoffiCType;
+    /** @deprecated */ export function callback(definition: string): IKoffiCType;
+    /** @deprecated */ export function callback(name: string, result: TypeSpec, arguments: TypeSpec[]): IKoffiCType;
+    /** @deprecated */ export function callback(convention: string, 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 as(value: any, type: TypeSpec): IKoffiPointerCast;
+    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 address(value: any): bigint;
+    export function call(value: any, type: TypeSpec, ...args: any[]): any;
+    export function encode(ref: any, type: TypeSpec, value: any): void;
+    export function encode(ref: any, type: TypeSpec, value: any, len: number): void;
+    export function encode(ref: any, offset: number, type: TypeSpec): void;
+    export function encode(ref: any, offset: number, type: TypeSpec, value: any): void;
+    export function encode(ref: any, offset: number, type: TypeSpec, value: any, len: number): void;
+
+    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>;
+    export function stats(): Record<string, unknown>;
+
+    export function alloc(type: TypeSpec, length: number): any;
+    export function free(value: any): void;
+
+    export function errno(): number;
+    export function errno(value: number): number;
+
+    export function reset(): void;
+
+    export const internal: Boolean;
+    export const extension: String;
+
+    export const os: {
+        errno: Record<string, number>
+    };
+
+    export const types: Record<string, IKoffiCType>;
+}

package/index.js

@@ -0,0 +1,51 @@
+// Copyright 2023 Niels Martignène <niels.martignene@protonmail.com>
+//
+// 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.
+
+// Adapted by Stephan 'Septh' Schreiber
+const { platform, arch } = require('node:process')
+const { deprecate } = require('node:util')
+
+let native
+if (platform === 'linux' && arch === 'x64') {
+    try {
+        native = require(`@septh/koffi-linux-x64-glibc`)
+    }
+    catch {
+        native = require(`@septh/koffi-linux-x64-musl`)
+    }
+}
+else native = require(`@septh/koffi-${platform}-${arch}`)
+
+module.exports = {
+    ...native,
+
+    // Deprecated functions in Koffi 2.x
+    handle: deprecate(native.opaque, "The koffi.handle() function was deprecated in Koffi 2.1, use koffi.opaque() instead", "KOFFI001"),
+    callback: deprecate(native.proto, "The koffi.callback() function was deprecated in Koffi 2.4, use koffi.proto() instead", "KOFFI002"),
+    load: (...args) => {
+        const lib = native.load(...args)
+        lib.cdecl = deprecate((...args2) => lib.func("__cdecl", ...args2), "The koffi.cdecl() function was deprecated in Koffi 2.7, use koffi.func(...) instead", "KOFFI003")
+        lib.stdcall = deprecate((...args2) => lib.func("__stdcall", ...args2), 'The koffi.stdcall() function was deprecated in Koffi 2.7, use koffi.func("__stdcall", ...) instead', "KOFFI004")
+        lib.fastcall = deprecate((...args2) => lib.func("__fastcall", ...args2), 'The koffi.fastcall() function was deprecated in Koffi 2.7, use koffi.func("__fastcall", ...) instead', "KOFFI005")
+        lib.thiscall = deprecate((...args2) => lib.func("__thiscall", ...args2), 'The koffi.thiscall() function was deprecated in Koffi 2.7, use koffi.func("__thiscall", ...) instead', "KOFFI006")
+        return lib
+    }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "koffi-cream",
+  "version": "2.11.0",
+  "description": "A lighter packaging for Koffi, the fast and simple C FFI (foreign function interface) for Node.js",
+  "author": {
+    "name": "Stephan 'Septh' Schreiber",
+    "email": "septh@sfr.fr",
+    "url": "https://github.com/Septh"
+  },
+  "contributors": [
+    {
+      "name": "Niels Martignène",
+      "email": "niels.martignene@protonmail.com",
+      "url": "https://koromix.dev/"
+    }
+  ],
+  "keywords": [
+    "foreign",
+    "function",
+    "interface",
+    "ffi",
+    "binding",
+    "c",
+    "napi",
+    "koffi"
+  ],
+  "homepage": "https://github.com/Septh/koffi-cream#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Septh/koffi-cream.git",
+    "directory": "packages/koffi-cream"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": "^12.22.0 || ^14.17.0 || ^15.12.0 || >= 16",
+    "npm": ">= 10.4.0",
+    "pnpm": ">= 7.1.0",
+    "yarn": ">= 3.2.0"
+  },
+  "type": "commonjs",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "optionalDependencies": {
+    "@septh/koffi-darwin-arm64": "2.11.0",
+    "@septh/koffi-darwin-x64": "2.11.0",
+    "@septh/koffi-freebsd-arm64": "2.11.0",
+    "@septh/koffi-freebsd-x64": "2.11.0",
+    "@septh/koffi-linux-arm64": "2.11.0",
+    "@septh/koffi-linux-riscv64": "2.11.0",
+    "@septh/koffi-linux-x64-glibc": "2.11.0",
+    "@septh/koffi-linux-x64-musl": "2.11.0",
+    "@septh/koffi-openbsd-x64": "2.11.0",
+    "@septh/koffi-win32-arm64": "2.11.0",
+    "@septh/koffi-win32-x64": "2.11.0"
+  }
+}