Node.js documentation (#368)

* Document TypeScript API


Co-authored-by: David Hatch <david@osohq.com>
Co-authored-by: Leina McDermott <leina05@gmail.com>
Co-authored-by: Sam Scott <sam@osohq.com>

docs/Makefile

@@ -11,6 +11,7 @@ BUILDDIR      = _build
 export BUNDLE_GEMFILE := $(abspath ../languages/ruby/Gemfile)
 export RUBY_DIR := $(abspath ../languages/ruby)
 export JAVA_DIR := $(abspath ../languages/java/oso)
+export JS_DIR := $(abspath ../languages/js)
 
 
 rwildcard=$(foreach d,$(wildcard $(1:=/*)),$(call rwildcard,$d,$2) $(filter $(subst *,%,$2),$d))
@@ -19,6 +20,7 @@ JAVA_PACKAGE_JAR_PATH := $(JAVA_DIR)/target/oso-0.5.0.jar
 
 RUBY_FILES := $(call rwildcard,../languages/ruby/lib,*.rb)
 JAVA_FILES := $(call rwildcard ../languages/java/oso/src, *.java)
+JS_FILES := $(call rwildcard ../languages/js/src, *.ts)
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -38,7 +40,13 @@ _api_docs/java: $(JAVA_FILES)
 	rm -rf _api_docs/java
 	cp -R $(JAVA_DIR)/target/site/apidocs _api_docs/java
 
-_api_docs: _api_docs/ruby _api_docs/java
+_api_docs/js/node: $(JS_FILES)
+	mkdir -p _api_docs/js
+	make -C $(JS_DIR) docs
+	rm -rf _api_docs/js/node
+	cp -R $(JS_DIR)/docs _api_docs/js/node
+
+_api_docs: _api_docs/ruby _api_docs/java _api_docs/js/node
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
@@ -82,10 +90,17 @@ ruby-test:
 	cd examples/context/ruby && bundle exec rspec test_spec.rb
 	cd examples/inheritance/ruby && bundle exec rspec test_spec.rb
 
+nodejs-test:
+	$(MAKE) -C ../languages/js build
+	cd examples/rbac/nodejs && yarn && yarn jest
+	cd examples/abac/nodejs && yarn && yarn jest
+	cd examples/context/nodejs && yarn && yarn jest
+
 test: doctest
 	$(MAKE) python-test
 	$(MAKE) ruby-test
 	$(MAKE) java-test
+	$(MAKE) nodejs-test
 
 deps:
 	pip3 install -r requirements-docs.txt

docs/changelogs/vNEXT.rst

@@ -4,6 +4,16 @@ NEXT
 
 **Release date:** XXXX-XX-XX
 
+Major news
+==========
+
+Node.js support
+---------------
+
+oso now supports applications written in Node.js, using our
+:doc:`Node.js library </using/libraries/node/index>`. Download :doc:`here
+</download>`.
+
 Breaking changes
 ================
 

docs/conf.py

@@ -98,6 +98,7 @@ def _skip(self, word):
     "changelogs/vTEMPLATE.rst",
     "**.pytest_cache**",
     "ruby/README.md",
+    "js/README.md",
     "more/language/polar-classes.rst",  # we don't currently have classes
     "**/venv/**",
     "**/node_modules/**",
@@ -181,6 +182,7 @@ def _skip(self, word):
 
 doctest_test_doctest_blocks = ""
 
+lexers["node"] = lexer.NodeShellLexer()
 lexers["polar"] = lexer.PolarLexer()
 lexers["jshell"] = lexer.JShellLexer()
 lexers["oso"] = lexer.OsoLexer()

docs/download.rst

@@ -112,9 +112,44 @@ oso is available as a library in several languages:
             - OS X
             - Windows
 
+    .. group-tab:: Node.js
+
+        The Node.js version of oso is available on NPM_ and can be installed
+        globally with NPM::
+
+            $ npm install -g oso@{release}
+
+        or added as a dependency to a project's ``package.json`` manifest with
+        NPM::
+
+            $ npm install oso@{release}
+
+        or Yarn::
+
+            $ yarn add oso@{release}
+
+        For more information on the oso Node.js library, see the :doc:`library
+        documentation </using/libraries/node/index>`.
+
+        .. admonition:: What's next
+            :class: tip
+
+            After you've installed oso, check out the
+            :doc:`/getting-started/quickstart`.
+
+        **Requirements**
+
+        - Node.js version 10 or greater
+        - Supported platforms:
+            - Linux
+            - OS X
+            - Windows
+
+        .. _NPM: https://www.npmjs.com/package/oso
+
 **Libraries coming soon:**
 
-- JavaScript / TypeScript
+- JavaScript in the browser
 - Go
 - Rust
 

docs/examples/abac/nodejs/01-simple.js

@@ -0,0 +1,92 @@
+const { Oso } = require('oso');
+
+const oso = new Oso();
+
+const EXPENSES = [
+  { amount: 500, submitted_by: 'alice', location: 'NYC', project_id: 2 },
+];
+
+// expense-class-start
+class Expense {
+  constructor({ amount, submitted_by, location, project_id }) {
+    // ...
+    this.amount = amount;
+    this.submitted_by = submitted_by;
+    this.location = location;
+    this.project_id = project_id;
+  }
+
+  static id(id) {
+    if (id < EXPENSES.length) return new Expense({ ...EXPENSES[id] });
+    return new Expense();
+  }
+}
+
+oso.registerClass(Expense);
+
+const MANAGERS = {
+  cora: ['bhavik'],
+  bhavik: ['alice'],
+};
+
+// user-class-start
+class User {
+  constructor(name, location) {
+    // ...
+    this.name = name;
+    this.location = location || 'NYC';
+  }
+
+  *employees() {
+    if (MANAGERS[this.name]) {
+      for (const name in MANAGERS[this.name]) {
+        yield new User(name);
+      }
+    }
+  }
+}
+
+oso.registerClass(User);
+
+class Project {
+  constructor(id, teamId) {
+    this.id = id;
+    this.teamId = teamId;
+  }
+
+  static id(id) {
+    return new Project(id, 0);
+  }
+}
+
+oso.registerClass(Project);
+
+class Team {
+  constructor(organizationId) {
+    this.organizationId = organizationId;
+  }
+
+  static id() {
+    return new Team(0);
+  }
+}
+
+oso.registerClass(Team);
+
+class Organization {
+  constructor(name) {
+    this.name = name;
+  }
+
+  static id() {
+    return new Organization('ACME');
+  }
+}
+
+oso.registerClass(Organization);
+
+module.exports = {
+  Expense,
+  oso,
+  User,
+};

docs/examples/abac/nodejs/abac.test.js

@@ -0,0 +1,35 @@
+const { oso, Expense, User } = require('./01-simple');
+
+const EXPENSES_DEFAULT = {
+  submitted_by: 'steve',
+  location: 'NYC',
+  amount: 50,
+  project_id: 2,
+};
+const sam = new User('sam');
+
+test('01-simple', async () => {
+  await oso.loadFile('../01-simple.polar');
+  const samEx = new Expense({ ...EXPENSES_DEFAULT, submitted_by: sam.name });
+  expect(await oso.isAllowed(sam, 'view', samEx)).toBe(true);
+  const steveEx = new Expense({ ...EXPENSES_DEFAULT });
+  expect(await oso.isAllowed(sam, 'view', steveEx)).toBe(false);
+});
+
+test('02-rbac', async () => {
+  await oso.loadFile('../02-rbac.polar');
+  await oso.loadStr(
+    'role(_: User { name: "sam" }, "admin", _: Project { id: 2 });'
+  );
+  const proj0Ex = new Expense({ ...EXPENSES_DEFAULT, project_id: 0 });
+  expect(await oso.isAllowed(sam, 'view', proj0Ex)).toBe(false);
+  const proj2Ex = new Expense({ ...EXPENSES_DEFAULT });
+  expect(await oso.isAllowed(sam, 'view', proj2Ex)).toBe(true);
+});
+
+test('03-hierarchy', async () => {
+  await oso.loadFile('../03-hierarchy.polar');
+  const bhavik = new User('bhavik');
+  const aliceEx = new Expense({ ...EXPENSES_DEFAULT, submitted_by: 'alice' });
+  expect(await oso.isAllowed(bhavik, 'view', aliceEx)).toBe(true);
+});

docs/examples/abac/nodejs/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "oso-docs-abac",
+  "version": "0",
+  "main": "n/a",
+  "license": "Apache-2.0",
+  "private": true,
+  "dependencies": {
+    "jest": "^26.4.2",
+    "oso": "../../../../languages/js"
+  }
+}