/mod.ts | plug@1.0.1

import * as plug from "https://deno.land/x/plug@1.0.1/mod.ts";

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.

Examples

Example 1

import { dlopen } from "https://deno.land/x/plug/mod.ts";

// 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 2

import { dlopen, FetchOptions } from "https://deno.land/x/plug/mod.ts";

// 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 3

import { dlopen, FetchOptions } from "https://deno.land/x/plug/mod.ts";

// 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`,
  },
};

await dlopen(options, {});

Example 4

import { dlopen, FetchOptions } from "https://deno.land/x/plug/mod.ts";

// 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, {});

Functions

f dlopen	Opens a dynamic library and registers symbols, compatible with Deno.dlopen yet with extended functionality allowing you to use remote (or local) binaries, automatically building the binary name and controlling the caching policy.
f download	Downloads a file using the specified FetchOptions

Interfaces

I CacheOptions	Options for controlling how plug caches files
I CrossOptions	Options for fetching cross-platform urls.
I NamedOptions	Options used for automatically assembling an os and arch specific file name
I URLOptions	Options for using a single url as the source for either creating a named url or using it simply as is if the platforms extension is specified or no name is specified.

Type Aliases

T ArchRecord	A record keyed by possible system architecture identifiers
T CacheLocation	Where the plug cache is stored:
T CacheSetting	A setting that determines how the cache is handled for remote dependencies.
T FetchOptions	Options for fetching files (usually being dynamic libraries, but could possibly also be other dependencies) using plug. This can be either a string or an URL. All urls in plug can be either local or remote. If it is not an string or URL it can be some combination of the following options:
T NestedCrossRecord	An optionally nested record of either an OsRecord or ArchRecord containing either the generic T or the opposite record type from the parent. That way we can query for the record entry of a target keyed by both an architecture and operating system in the ordered entered in this record.
T OsRecord	A record keyed by possible operating system identifiers