spicedb-embedded 0.1.0 → 0.1.5

package/README.md

@@ -1,23 +1,94 @@
-# spicedb-embedded (Node.js)
+# spicedb-embedded
 
-Embedded [SpiceDB](https://authzed.com/spicedb) for Node.js — authorization server for tests and development. Uses the shared/c C library via koffi FFI and connects over gRPC via Unix sockets or TCP. Supports memory (default), postgres, cockroachdb, spanner, and mysql datastores. **Node.js only** (not for browser/frontend).
+Sometimes you need a simple way to run access checks without spinning up a new service. This library provides an embedded version of [SpiceDB](https://authzed.com/spicedb) in various languages. Each implementation is based on a C-shared library (compiled from the SpiceDB source code) with a very thin FFI binding on top of it. This means that it runs the native SpiceDB code within your already-running process.
+
+```typescript
+import { v1, EmbeddedSpiceDB } from "spicedb-embedded";
+
+const schema = `definition user {} definition document { relation reader: user permission read = reader }`;
+const rel = v1.Relationship.create({
+  resource: v1.ObjectReference.create({
+    objectType: "document",
+    objectId: "readme",
+  }),
+  relation: "reader",
+  subject: v1.SubjectReference.create({
+    object: v1.ObjectReference.create({
+      objectType: "user",
+      objectId: "alice",
+    }),
+  }),
+});
+
+const spicedb = await EmbeddedSpiceDB.create(schema, [rel]);
+const resp = await spicedb.permissions().promises.checkPermission(
+  v1.CheckPermissionRequest.create({
+    resource: v1.ObjectReference.create({
+      objectType: "document",
+      objectId: "readme",
+    }),
+    permission: "read",
+    subject: v1.SubjectReference.create({
+      object: v1.ObjectReference.create({
+        objectType: "user",
+        objectId: "alice",
+      }),
+    }),
+  })
+);
+spicedb.close();
+```
+
+## Who should consider using this?
+
+If you want to spin up SpiceDB, but don't want the overhead of managing another service, this might be for you.
+
+If you want an embedded server for your unit tests and don't have access to Docker / Testcontainers, this might be for you.
+
+If you have a schema and set of permissions that are static / readonly, this might be for you.
+
+## Who should avoid using this?
+
+If you live in a world of microservices that each need to perform permission checks, you should almost certainly spin up a centralized SpiceDB deployment.
+
+If you want visibility into metrics for SpiceDB, you should avoid this.
+
+## How does storage work?
+
+The default datastore is "memory" (memdb). If you use this datastore, keep in mind that it will reset on each app startup. This is a great option if you can easily provide your schema and relationships at runtime. This way, there are no external network calls to check relationships at runtime.
+
+If you need a longer term storage, you can use any SpiceDB-compatible datastores.
+
+```typescript
+import { EmbeddedSpiceDB } from "spicedb-embedded";
+
+// Run migrations first: spicedb datastore migrate head --datastore-engine postgres --datastore-conn-uri "postgres://..."
+const schema = `definition user {} definition document { relation reader: user permission read = reader }`;
+const spicedb = await EmbeddedSpiceDB.create(schema, [], {
+  datastore: "postgres",
+  datastore_uri: "postgres://user:pass@localhost:5432/spicedb",
+});
+// Use full Permissions API (writeRelationships, checkPermission, etc.)
+spicedb.close();
+```
+
+## Running code written in Go compiled to a C-shared library within my service sounds scary
+
+It is scary! Using a C-shared library via FFI bindings introduces memory management in languages that don't typically have to worry about it.
+
+However, this library purposely limits the FFI layer. The only thing it is used for is to spawn the SpiceDB server (and to dispose of it when you shut down the embedded server). Once the SpiceDB server is running, it exposes a gRPC interface that listens over Unix Sockets (default on Linux/macOS) or TCP (default on Windows).
+
+So you get the benefits of (1) using the same generated gRPC code to communicate with SpiceDB that would in a non-embedded world, and (2) communication happens out-of-band so that no memory allocations happen in the FFI layer once the embedded server is running.
 
 ## Comparison with SpiceDB WASM
 
-SpiceDB also provides a [WebAssembly (WASM) build](https://authzed.com/blog/some-assembly-required) used in the [Authzed Playground](https://play.authzed.com). This Node.js implementation differs in several important ways:
+SpiceDB also provides a [WebAssembly (WASM) build](https://authzed.com/blog/some-assembly-required) used in the [Authzed Playground](https://play.authzed.com).
 
-| Aspect           | **spicedb-embedded** (this package)                                  | **SpiceDB WASM**                                       |
-| ---------------- | -------------------------------------------------------------------- | ------------------------------------------------------ |
-| **Runtime**      | Node.js only (native addon)                                          | Browser + Node.js (via WASM)                           |
-| **Architecture** | Spawns real SpiceDB server via C/CGO FFI; full gRPC over Unix socket | Compiled Go→WASM; callback-based development API       |
-| **API**          | Full SpiceDB gRPC API (Permissions, Schema, Watch, etc.)             | Development API only (check, validate, run operations) |
-| **Use case**     | Server-side tests, development, local tooling                        | Browser Playground, client-side validation             |
-| **Performance**  | Native SpiceDB; full caching, production-grade                       | No Ristretto cache; simplified for WASM                |
-| **Distribution** | Requires platform-specific `libspicedb.so`/`.dylib`                  | Single `.wasm` file (~25MB)                            |
+The WASM only provides a small subset of the functionality of SpiceDB, but it has the advantage of working within the context of a browser.
 
-**When to use this package:** Node.js applications that need an embedded SpiceDB for integration tests, local development, or tooling. You get the real SpiceDB implementation with the full API.
+**When to use this package:** Node.js applications that want access to full set of APIs that SpiceDB offers.
 
-**When to use WASM:** Browser-based tools (e.g., schema playground) or when you need a single portable binary.
+**When to use WASM:** Browser-based tools.
 
 ## Installation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spicedb-embedded",
-  "version": "0.1.0",
+  "version": "0.1.5",
   "description": "Embedded SpiceDB for TypeScript/Node.js — in-memory authorization using the standard gRPC API",
   "type": "module",
   "main": "dist/index.js",