denosaurs/plug

🔌 Deno FFI helper module

plug

Plug is a drop in extension for using remote dynamic libraries in deno. It automatically handles caching and loading with minimal overhead. It can automatically create the URL for your cross-operating-system, cross-architecture libraries if you so wish using a simple configuration which deviates from the standard URL/string path input.

Installation

Plug is published to jsr.io and deno.land. The recommended way to use it is to use JSR:

deno add @denosaurs/plug

or without the CLI:

import * as plug from "jsr:@denosaurs/plug";

Example using plug as an almost drop in replacement for Deno.dlopen

import { dlopen } from "@denosaurs/plug";

// Drop-in replacement for `Deno.dlopen` which fetches the following depending
// on operating system:
// * darwin: "https://example.com/some/path/libexample.dylib"
// * windows: "https://example.com/some/path/example.dll"
// * linux: "https://example.com/some/path/libexample.so"
const library = await dlopen("https://example.com/some/path/", {
  noop: { parameters: [], result: "void" },
});

library.symbols.noop();

Example using automatic binary name guessing

import { dlopen, FetchOptions } from "@denosaurs/plug";

// If you want plug to guess your binary names
const options: FetchOptions = {
  name: "example",
  url: "https://example.com/some/path/",
  // Becomes:
  // darwin: "https://example.com/some/path/libexample.dylib"
  // windows: "https://example.com/some/path/example.dll"
  // linux: "https://example.com/some/path/libexample.so"
};

const library = await dlopen(options, {
  noop: { parameters: [], result: "void" },
});

library.symbols.noop();

Example using nested cross-platform options

import { dlopen, FetchOptions } from "@denosaurs/plug";

// Also you can specify the path for certain architecture
const options: FetchOptions = {
  name: "example",
  url: {
    darwin: {
      aarch64: `https://example.com/some/path/libexample.aarch64.dylib`,
      x86_64: `https://example.com/some/path/libexample.x86_64.dylib`,
    },
    windows: `https://example.com/some/path/example.dll`,
    linux: `https://example.com/some/path/libexample.so`,
    freebsd: "https://example.com/some/path/libexample_freebsd.so",
    netbsd: "https://example.com/some/path/libexample_netbsd.so",
    aix: "https://example.com/some/path/libexample_aix.so",
    solaris: "https://example.com/some/path/libexample_solaris.so",
    illumos: "https://example.com/some/path/libexample_illumos.so",
  },
};

await dlopen(options, {});

Example using nested cross-platform options and automatic binary name guessing

import { dlopen, FetchOptions } from "@denosaurs/plug";

// Or even configure plug to automatically guess the binary names for you,
// even when there are special rules for naming on specific architectures
const options: FetchOptions = {
  name: "test",
  url: "https://example.com/some/path/",
  suffixes: {
    darwin: {
      aarch64: ".aarch64",
      x86_64: ".x86_64",
    },
  },
  // Becomes:
  // darwin-aarch64: "https://example.com/some/path/libexample.aarch64.dylib"
  // darwin-x86_64: "https://example.com/some/path/libexample.x86_64.dylib"
};

await dlopen(options, {});

Testing

To run the plug tests, you can use the following command:

deno test --import-map test_import_map.json -A --doc

The test_import_map.json file is used to map the @denosaurs/plug import to the local mod.ts file instead of the remote one for the documentation tests.

Other

Related

• deno_plugin_prepare - A library for managing deno native plugin dependencies
• cache - Deno cache library

Contribution

Pull request, issues and feedback are very welcome. Code style is formatted with deno fmt and commit messages are done following Conventional Commits spec.

Licence

Copyright 2020-2024, the denosaurs team. All rights reserved. MIT license.