npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@open-policy-agent/opa-wasm

v1.8.1

Published

Open Policy Agent WebAssembly SDK

Downloads

144,519

Readme

Work in Progress -- Contributions welcome!!

Open Policy Agent WebAssemby NPM Module

This is the source for the @open-policy-agent/opa-wasm NPM module which is a small SDK for using WebAssembly (wasm) compiled Open Policy Agent Rego policies.

Getting Started

Install the module

npm install @open-policy-agent/opa-wasm

Usage

There are only a couple of steps required to start evaluating the policy.

Import the module

const { loadPolicy } = require("@open-policy-agent/opa-wasm");

Load the policy

loadPolicy(policyWasm);

The loadPolicy function returns a Promise with the loaded policy. Typically this means loading it in an async function like:

const policy = await loadPolicy(policyWasm);

Or something like:

loadPolicy(policyWasm).then((policy) => {
  // evaluate or save the policy
}, (error) => {
  console.error("Failed to load policy: " + error);
});

The policyWasm needs to be either the raw byte array of the compiled policy Wasm file, or a WebAssembly module.

For example:

const fs = require("fs");

const policyWasm = fs.readFileSync("policy.wasm");

Alternatively the bytes can be pulled in remotely from a fetch or in some cases (like CloudFlare Workers) the Wasm binary can be loaded directly into the javascript context through external APIs.

Evaluate the Policy

The loaded policy object returned from loadPolicy() has a couple of important APIs for policy evaluation:

setData(data) -- Provide an external data document for policy evaluation.

  • data MUST be a serializable object or ArrayBuffer, which assumed to be a well-formed stringified JSON

evaluate(input) -- Evaluates the policy using any loaded data and the supplied input document.

  • input parameter MAY be an object, primitive literal or ArrayBuffer, which assumed to be a well-formed stringified JSON

ArrayBuffer supported in the APIs above as a performance optimisation feature, given that either network or file system provided contents can easily be represented as ArrayBuffer in a very performant way.

Example:

input = '{"path": "/", "role": "admin"}';

loadPolicy(policyWasm).then((policy) => {
  resultSet = policy.evaluate(input);
  if (resultSet == null) {
    console.error("evaluation error");
  } else if (resultSet.length == 0) {
    console.log("undefined");
  } else {
    console.log("allowed = " + resultSet[0].result);
  }
}).catch((error) => {
  console.error("Failed to load policy: ", error);
});

For any opa build created WASM binaries the result set, when defined, will contain a result key with the value of the compiled entrypoint. See https://www.openpolicyagent.org/docs/latest/wasm/ for more details.

Writing the policy

See https://www.openpolicyagent.org/docs/latest/how-do-i-write-policies/

Compiling the policy

Either use the Compile REST API or opa build CLI tool.

For example, with OPA v0.20.5+:

opa build -t wasm -e example/allow example.rego

Which is compiling the example.rego policy file with the result set to data.example.allow. The result will be an OPA bundle with the policy.wasm binary included. See ./examples for a more comprehensive example.

See opa build --help for more details.

Development

Lint and Format checks

This project is using Deno's lint and formatter tools in CI. With deno installed locally, the same checks can be invoked using npm:

  • npm run lint
  • npm run fmt -- this will fix the formatting
  • npm run fmt:check -- this happens in CI

All of these operate on git-tracked files, so make sure you've committed the code you'd like to see checked. Alternatively, you can invoke deno lint my_new_file.js directly, too.

Build

The published package provides four different entrypoints for consumption:

  1. A CommonJS module for consumption with older versions of Node or those using require():
    const { loadPolicy } = require("@open-policy-agent/opa-wasm");
  2. An ESM module for consumption with newer versions of Node:
    import { loadPolicy } from "@open-policy-agent/opa-wasm";
  3. An ESM module for consumption in modern browsers (this will contain all dependencies already bundled and can be used standalone).
    <script type="module">
    import opa from 'https://unpkg.com/@open-policy-agent/opa-wasm@latest/dist/opa-wasm-browser.esm.js';
    opa.loadPolicy(...);
    </script>
  4. A script for consumption in all browsers (this will export an opa global variable).
    <script src="https://unpkg.com/@open-policy-agent/opa-wasm@latest/dist/opa-wasm-browser.js"></script>
    <script>
    opa.loadPolicy(...);
    </script>

The browser builds are generated in the ./build.sh script and use esbuild. All exports are defined in the exports field in the package.json file. More detials on how these work are described in the Conditional Exports documentation.

For TypeScript projects we also generate an opa.d.ts declaration file that will give correct typings and is also defined under the types field in the package.json.