Jsdocs

packages/solid/src/resource/Resource.ts

@@ -536,6 +536,12 @@ export abstract class Resource extends (EventEmitter as new () => TypedEmitter<{
    * ===========================================================================
    */
 
+  /**
+   * Retrieves the URI for the web access control (WAC) rules for this resource
+   * @param options - set the "ignoreCache" field to true to ignore any cached
+   * information on WAC rules.
+   * @returns WAC Rules results
+   */
   protected async getWacUri(options?: {
     ignoreCache: boolean;
   }): Promise<GetWacUriResult> {
@@ -559,6 +565,34 @@ export abstract class Resource extends (EventEmitter as new () => TypedEmitter<{
     return wacUriResult;
   }
 
+  /**
+   * Retrieves web access control (WAC) rules for this resource
+   * @param options - set the "ignoreCache" field to true to ignore any cached
+   * information on WAC rules.
+   * @returns WAC Rules results
+   *
+   * @example
+   * ```typescript
+   * const resource = ldoSolidDataset
+   *   .getResource("https://example.com/container/resource.ttl");
+   * const wacRulesResult = await resource.getWac();
+   * if (!wacRulesResult.isError) {
+   *   const wacRules = wacRulesResult.wacRule;
+   *   // True if the resource is publicly readable
+   *   console.log(wacRules.public.read);
+   *   // True if authenticated agents can write to the resource
+   *   console.log(wacRules.authenticated.write);
+   *   // True if the given WebId has append access
+   *   console.log(
+   *     wacRules.agent[https://example.com/person1/profile/card#me].append
+   *   );
+   *   // True if the given WebId has control access
+   *   console.log(
+   *     wacRules.agent[https://example.com/person1/profile/card#me].control
+   *   );
+   * }
+   * ```
+   */
   async getWac(options?: {
     ignoreCache: boolean;
   }): Promise<GetWacUriError | GetWacRuleResult> {
@@ -599,12 +633,53 @@ export abstract class Resource extends (EventEmitter as new () => TypedEmitter<{
     return parentResource.getWac();
   }
 
+  /**
+   * Sets access rules for a specific resource
+   * @param wacRule - the access rules to set
+   * @returns SetWacRuleResult
+   *
+   * @example
+   * ```typescript
+   * const resource = ldoSolidDataset
+   *   .getResource("https://example.com/container/resource.ttl");
+   * const wacRulesResult = await resource.setWac({
+   *   public: {
+   *     read: true,
+   *     write: false,
+   *     append: false,
+   *     control: false
+   *   },
+   *   authenticated: {
+   *     read: true,
+   *     write: false,
+   *     append: true,
+   *     control: false
+   *   },
+   *   agent: {
+   *     "https://example.com/person1/profile/card#me": {
+   *       read: true,
+   *       write: true,
+   *       append: true,
+   *       control: true
+   *     }
+   *   }
+   * });
+   * ```
+   */
   async setWac(wacRule: WacRule): Promise<GetWacUriError | SetWacRuleResult> {
     const wacUriResult = await this.getWacUri();
     if (wacUriResult.isError) return wacUriResult;
 
-    return setWacRuleForAclUri(wacUriResult.wacUri, wacRule, this.uri, {
-      fetch: this.context.fetch,
-    });
+    const result = await setWacRuleForAclUri(
+      wacUriResult.wacUri,
+      wacRule,
+      this.uri,
+      {
+        fetch: this.context.fetch,
+      },
+    );
+    if (result.isError) return result;
+    this.wacRule = result.wacRule;
+    return result;
   }
 }

packages/solid/src/resource/wac/WacRule.ts

@@ -1,3 +1,6 @@
+/**
+ * A list of modes that a certain agent has access to
+ */
 export interface AccessModeList {
   read: boolean;
   append: boolean;
@@ -5,6 +8,9 @@ export interface AccessModeList {
   control: boolean;
 }
 
+/**
+ * A list of modes for each kind of agent
+ */
 export interface WacRule {
   public: AccessModeList;
   authenticated: AccessModeList;

packages/solid/src/resource/wac/getWacRule.ts

@@ -20,6 +20,12 @@ export type GetWacRuleResult =
   | GetWacRuleError
   | WacRuleAbsent;
 
+/**
+ * Given the URI of an ACL document, return the Web Access Control (WAC) rules
+ * @param aclUri: The URI for the ACL document
+ * @param options: Options object to include an authenticated fetch function
+ * @returns GetWacRuleResult
+ */
 export async function getWacRuleWithAclUri(
   aclUri: string,
   options?: BasicRequestOptions,

packages/solid/src/resource/wac/getWacUri.ts

@@ -18,6 +18,12 @@ export type GetWacUriError =
   | UnexpectedResourceError;
 export type GetWacUriResult = GetWacUriSuccess | GetWacUriError;
 
+/**
+ * Get the URI for the WAC rules of a specific resource
+ * @param resourceUri: the URI of the resource
+ * @param options: Options object to include an authenticated fetch function
+ * @returns GetWacUriResult
+ */
 export async function getWacUri(
   resourceUri: string,
   options?: BasicRequestOptions,

packages/solid/src/resource/wac/results/GetWacRuleSuccess.ts

@@ -1,7 +1,13 @@
 import type { ResourceSuccess } from "../../../requester/results/success/SuccessResult";
 import type { WacRule } from "../WacRule";
 
+/**
+ * Returned when a WAC rule is successfully retrieved
+ */
 export interface GetWacRuleSuccess extends ResourceSuccess {
   type: "getWacRuleSuccess";
+  /**
+   * The rule that was retrieved
+   */
   wacRule: WacRule;
 }

packages/solid/src/resource/wac/results/GetWacUriSuccess.ts

@@ -1,7 +1,13 @@
 import type { ResourceSuccess } from "../../../requester/results/success/SuccessResult";
 import type { LeafUri } from "../../../util/uriTypes";
 
+/**
+ * Returned when the URI for a resources ACL document was successfully retried
+ */
 export interface GetWacUriSuccess extends ResourceSuccess {
   type: "getWacUriSuccess";
+  /**
+   * The URI of the ACL document
+   */
   wacUri: LeafUri;
 }

packages/solid/src/resource/wac/results/SetWacRuleSuccess.ts

@@ -1,7 +1,13 @@
 import type { ResourceSuccess } from "../../../requester/results/success/SuccessResult";
 import type { WacRule } from "../WacRule";
 
+/**
+ * Returned when rules were successfully written
+ */
 export interface SetWacRuleSuccess extends ResourceSuccess {
   type: "setWacRuleSuccess";
+  /**
+   * The written rule
+   */
   wacRule: WacRule;
 }

packages/solid/src/resource/wac/results/WacRuleAbsent.ts

@@ -1,5 +1,8 @@
 import type { ResourceSuccess } from "../../../requester/results/success/SuccessResult";
 
+/**
+ * Returned if no WAC rule was returned from the server
+ */
 export interface WacRuleAbsent extends ResourceSuccess {
   type: "wacRuleAbsent";
 }

packages/solid/src/resource/wac/setWacRule.ts

@@ -16,6 +16,15 @@ import { guaranteeFetch } from "../../util/guaranteeFetch";
 export type SetWacRuleError = HttpErrorResultType | UnexpectedResourceError;
 export type SetWacRuleResult = SetWacRuleSuccess | SetWacRuleError;
 
+/**
+ * Given the URI of an ACL document and some WAC rules, set the WAC rules of
+ * that document
+ * @param aclUri: The URI for the ACL document
+ * @param newRule: A new WAC rule to set. This will overwrite old rules
+ * @param accessTo: The document this rule refers to
+ * @param options: Options object to include an authenticated fetch function
+ * @returns SetWacRuleResult
+ */
 export async function setWacRuleForAclUri(
   aclUri: LeafUri,
   newRule: WacRule,