feat: Add @cerbos/files package to load policies from YAML or JSON …

…files (#611)

* Add `@cerbos/files` package to load policies from YAML or JSON files

Signed-off-by: Andrew Haines <[email protected]>

* Work around the exclusion of `@defaultValue` in generated docs

microsoft/rushstack#4249

Signed-off-by: Andrew Haines <[email protected]>

---------

Signed-off-by: Andrew Haines <[email protected]>

README.md

@@ -7,13 +7,15 @@ The Cerbos JavaScript SDK makes it easy to interact with the Cerbos PDP from you
 
 ## Packages
 
-For server-side Node.js applications, the [@cerbos/grpc](/packages/grpc/README.md) library provides a client ([`GRPC`](/docs/grpc.grpc.md)) for interacting with the Cerbos PDP over gRPC.
+For server-side Node.js applications, the [@cerbos/grpc](/packages/grpc/README.md) package provides a client ([`GRPC`](/docs/grpc.grpc.md)) for interacting with the Cerbos PDP over gRPC.
 
-For browser-based applications, the [@cerbos/http](/packages/http/README.md) library provides a client ([`HTTP`](/docs/http.http.md)) for interacting with the Cerbos PDP over HTTP.
+For browser-based applications, the [@cerbos/http](/packages/http/README.md) package provides a client ([`HTTP`](/docs/http.http.md)) for interacting with the Cerbos PDP over HTTP.
 
 Both clients extend the base [`Client`](/docs/core.client.md) class from [@cerbos/core](/packages/core/README.md), so they can be used interchangeably in isomorphic applications.
 
-To instrument the clients with [OpenTelemetry](http://opentelemetry.io), use the [@cerbos/opentelemetry](/packages/opentelemetry/README.md) library.
+To instrument the clients with [OpenTelemetry](http://opentelemetry.io), use the [@cerbos/opentelemetry](/packages/opentelemetry/README.md) package.
+
+To load Cerbos policies from YAML or JSON files, use the [@cerbos/files](/packages/files/README.md) package.
 
 ## Further reading
 

docs/core.client.addorupdatepolicies.md

@@ -32,8 +32,9 @@ Requires
 
 - a dynamic [storage backend](https://docs.cerbos.dev/cerbos/latest/configuration/storage.html)<!-- -->.
 
-## Example
+## Example 1
 
+Create a policy in code:
 
 ```typescript
 await cerbos.addOrUpdatePolicies({
@@ -51,3 +52,28 @@ await cerbos.addOrUpdatePolicies({
 });
 ```
 
+## Example 2
+
+Load a policy from a YAML or JSON file with [readPolicy()](./files.readpolicy.md)<!-- -->:
+
+```typescript
+import { readPolicy } from "@cerbos/files";
+
+await cerbos.addOrUpdatePolicies({
+  policies: [await readPolicy("path/to/policy.yaml")],
+});
+```
+
+## Example 3
+
+Load policies and schemas from a directory with [readDirectory()](./files.readdirectory.md)<!-- -->:
+
+```typescript
+import { readDirectory } from "@cerbos/files";
+
+const { policies, schemas } = await readDirectory("path/to/directory");
+
+await cerbos.addOrUpdateSchemas({ schemas });
+await cerbos.addOrUpdatePolicies({ policies });
+```
+

docs/core.client.addorupdateschemas.md

@@ -32,18 +32,47 @@ Requires
 
 - a dynamic [storage backend](https://docs.cerbos.dev/cerbos/latest/configuration/storage.html)<!-- -->.
 
-## Example
+## Example 1
 
+Create a schema in code:
 
 ```typescript
-await cerbos.addOrUpdateSchemas([{
-  id: "document.json",
-  definition: `{
-    "type": "object",
-    "properties": {
-      "owner": { "type": "string" }
-    }
-  }`,
-}]);
+
+await cerbos.addOrUpdateSchemas({
+  schemas: [{
+    id: "document.json",
+    definition: {
+      type: "object",
+      properties: {
+        owner: { type: "string" }
+      }
+    },
+  }],
+});
+```
+
+## Example 2
+
+Load a schema from a JSON file with [readSchema()](./files.readschema.md)<!-- -->:
+
+```typescript
+import { readSchema } from "@cerbos/files";
+
+await cerbos.addOrUpdateSchemas({
+  schemas: [await readSchema("_schemas/path/to/schema.json")],
+});
+```
+
+## Example 3
+
+Load policies and schemas from a directory with [readDirectory()](./files.readdirectory.md)<!-- -->:
+
+```typescript
+import { readDirectory } from "@cerbos/files";
+
+const { policies, schemas } = await readDirectory("path/to/directory");
+
+await cerbos.addOrUpdateSchemas({ schemas });
+await cerbos.addOrUpdatePolicies({ policies });
 ```
 

docs/files.directorycontents.md

@@ -0,0 +1,21 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cerbos/files](./files.md) &gt; [DirectoryContents](./files.directorycontents.md)
+
+## DirectoryContents interface
+
+The contents of a directory, returned by [readDirectory()](./files.readdirectory.md)<!-- -->.
+
+**Signature:**
+
+```typescript
+export interface DirectoryContents 
+```
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [policies](./files.directorycontents.policies.md) |  | [Policy](./core.policy.md)<!-- -->\[\] | The policies found in the directory. |
+|  [schemas](./files.directorycontents.schemas.md) |  | [Schema](./files.schema.md)<!-- -->\[\] | The schemas found in the directory's <code>_schemas</code> subdirectory. |
+

docs/files.directorycontents.policies.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cerbos/files](./files.md) &gt; [DirectoryContents](./files.directorycontents.md) &gt; [policies](./files.directorycontents.policies.md)
+
+## DirectoryContents.policies property
+
+The policies found in the directory.
+
+**Signature:**
+
+```typescript
+policies: Policy[];
+```

docs/files.directorycontents.schemas.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cerbos/files](./files.md) &gt; [DirectoryContents](./files.directorycontents.md) &gt; [schemas](./files.directorycontents.schemas.md)
+
+## DirectoryContents.schemas property
+
+The schemas found in the directory's `_schemas` subdirectory.
+
+**Signature:**
+
+```typescript
+schemas: Schema[];
+```

docs/files.md

@@ -0,0 +1,25 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cerbos/files](./files.md)
+
+## files package
+
+Load Cerbos policies from YAML or JSON files.
+
+## Functions
+
+|  Function | Description |
+|  --- | --- |
+|  [parsePolicy(contents)](./files.parsepolicy.md) | Parse a policy from a YAML- or JSON-encoded string. |
+|  [readDirectory(path)](./files.readdirectory.md) | Read the policy and schema files in a directory and its subdirectories. |
+|  [readPolicy(path)](./files.readpolicy.md) | Read a policy from a YAML or JSON file. |
+|  [readSchema(path, options)](./files.readschema.md) | Read a schema from a JSON file. |
+
+## Interfaces
+
+|  Interface | Description |
+|  --- | --- |
+|  [DirectoryContents](./files.directorycontents.md) | The contents of a directory, returned by [readDirectory()](./files.readdirectory.md)<!-- -->. |
+|  [ReadSchemaOptions](./files.readschemaoptions.md) | Options for [readSchema()](./files.readschema.md)<!-- -->. |
+|  [Schema](./files.schema.md) | A JSON schema to be used to validate principal or resource attributes. |
+

docs/files.parsepolicy.md

@@ -0,0 +1,24 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cerbos/files](./files.md) &gt; [parsePolicy](./files.parsepolicy.md)
+
+## parsePolicy() function
+
+Parse a policy from a YAML- or JSON-encoded string.
+
+**Signature:**
+
+```typescript
+export declare function parsePolicy(contents: string): Policy;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  contents | string | the YAML- or JSON-encoded policy definition. |
+
+**Returns:**
+
+[Policy](./core.policy.md)
+

docs/files.readdirectory.md

@@ -0,0 +1,28 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cerbos/files](./files.md) &gt; [readDirectory](./files.readdirectory.md)
+
+## readDirectory() function
+
+Read the policy and schema files in a directory and its subdirectories.
+
+**Signature:**
+
+```typescript
+export declare function readDirectory(path: string): Promise<DirectoryContents>;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  path | string | the path to the directory. |
+
+**Returns:**
+
+Promise&lt;[DirectoryContents](./files.directorycontents.md)<!-- -->&gt;
+
+## Remarks
+
+This function looks for policies and schemas stored in the [standard Cerbos directory layout](https://docs.cerbos.dev/cerbos/latest/policies/best_practices.html#_policy_repository_layout)<!-- -->.
+

docs/files.readpolicy.md

@@ -0,0 +1,24 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cerbos/files](./files.md) &gt; [readPolicy](./files.readpolicy.md)
+
+## readPolicy() function
+
+Read a policy from a YAML or JSON file.
+
+**Signature:**
+
+```typescript
+export declare function readPolicy(path: string): Promise<Policy>;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  path | string | the path to the policy file. |
+
+**Returns:**
+
+Promise&lt;[Policy](./core.policy.md)<!-- -->&gt;
+

docs/files.readschema.md

@@ -0,0 +1,25 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cerbos/files](./files.md) &gt; [readSchema](./files.readschema.md)
+
+## readSchema() function
+
+Read a schema from a JSON file.
+
+**Signature:**
+
+```typescript
+export declare function readSchema(path: string, options?: ReadSchemaOptions): Promise<Schema>;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  path | string | the path to the schema file. |
+|  options | [ReadSchemaOptions](./files.readschemaoptions.md) | _(Optional)_ additional settings. |
+
+**Returns:**
+
+Promise&lt;[Schema](./files.schema.md)<!-- -->&gt;
+

docs/files.readschemaoptions.id.md

@@ -0,0 +1,18 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cerbos/files](./files.md) &gt; [ReadSchemaOptions](./files.readschemaoptions.md) &gt; [id](./files.readschemaoptions.id.md)
+
+## ReadSchemaOptions.id property
+
+Unique ID for the schema, to be used to reference the schema from policies and from other schemas.
+
+**Signature:**
+
+```typescript
+id?: string | undefined;
+```
+
+## Remarks
+
+If the schema is nested under a directory called `_schemas`<!-- -->, the default ID will be the file path relative to the `_schemas` directory. Otherwise, the default ID will be the file's basename.
+

docs/files.readschemaoptions.md

@@ -0,0 +1,20 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cerbos/files](./files.md) &gt; [ReadSchemaOptions](./files.readschemaoptions.md)
+
+## ReadSchemaOptions interface
+
+Options for [readSchema()](./files.readschema.md)<!-- -->.
+
+**Signature:**
+
+```typescript
+export interface ReadSchemaOptions 
+```
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [id?](./files.readschemaoptions.id.md) |  | string \| undefined | _(Optional)_ Unique ID for the schema, to be used to reference the schema from policies and from other schemas. |
+

docs/files.schema.definition.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cerbos/files](./files.md) &gt; [Schema](./files.schema.md) &gt; [definition](./files.schema.definition.md)
+
+## Schema.definition property
+
+Definition of the schema.
+
+**Signature:**
+
+```typescript
+definition: string;
+```

docs/files.schema.md

@@ -0,0 +1,21 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@cerbos/files](./files.md) &gt; [Schema](./files.schema.md)
+
+## Schema interface
+
+A JSON schema to be used to validate principal or resource attributes.
+
+**Signature:**
+
+```typescript
+export interface Schema extends SchemaInput 
+```
+**Extends:** [SchemaInput](./core.schemainput.md)
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [definition](./files.schema.definition.md) |  | string | Definition of the schema. |
+

docs/index.md

@@ -9,6 +9,7 @@
 |  Package | Description |
 |  --- | --- |
 |  [@cerbos/core](./core.md) | Common types used by the [gRPC](./grpc.md) and [HTTP](./http.md) client libraries. |
+|  [@cerbos/files](./files.md) | Load Cerbos policies from YAML or JSON files. |
 |  [@cerbos/grpc](./grpc.md) | Client library for interacting with the Cerbos policy decision point over gRPC from server-side Node.js applications. |
 |  [@cerbos/http](./http.md) | Client library for interacting with the Cerbos policy decision point over HTTP from browser-based applications. |
 |  [@cerbos/lite](./lite.md) | Client library for interacting with WebAssembly Cerbos policy bundles from server-side Node.js and browser-based applications. |