From 5bf1113e61b9ba2da1a47335ff4d5f88b023442f Mon Sep 17 00:00:00 2001 From: Jackson Morgan Date: Thu, 2 Jan 2025 19:10:59 -0500 Subject: [PATCH] Added documentation --- .../src/requester/requests/deleteResource.ts | 25 +++++----- packages/solid/src/resource/Resource.ts | 46 ++++++++++++++++--- .../notifications/NotificationMessage.ts | 3 ++ .../notifications/NotificationSubscription.ts | 13 ++++++ .../results/NotificationErrors.ts | 4 ++ 5 files changed, 72 insertions(+), 19 deletions(-) diff --git a/packages/solid/src/requester/requests/deleteResource.ts b/packages/solid/src/requester/requests/deleteResource.ts index 8b5baaa..cc8f084 100644 --- a/packages/solid/src/requester/requests/deleteResource.ts +++ b/packages/solid/src/requester/requests/deleteResource.ts @@ -7,6 +7,8 @@ import { UnexpectedHttpError } from "../results/error/HttpErrorResult"; import { HttpErrorResult } from "../results/error/HttpErrorResult"; import type { DeleteSuccess } from "../results/success/DeleteSuccess"; import type { DatasetRequestOptions } from "./requestOptions"; +import type { IBulkEditableDataset } from "@ldo/subscribable-dataset"; +import type { Quad } from "@rdfjs/types"; /** * All possible return values for deleteResource @@ -62,7 +64,8 @@ export async function deleteResource( // if it hasn't been deleted when you're unauthenticated. 404 happens when // the document never existed if (response.status === 205 || response.status === 404) { - updateDatasetOnSuccessfulDelete(uri, response.status === 205, options); + if (options?.dataset) + updateDatasetOnSuccessfulDelete(uri, options.dataset); return { isError: false, type: "deleteSuccess", @@ -77,20 +80,16 @@ export async function deleteResource( } /** - * TODO + * Assuming a successful delete has just been performed, this function updates + * datastores to reflect that. + * + * @param uri - The uri of the resouce that was removed + * @param dataset - The dataset that should be updated */ export function updateDatasetOnSuccessfulDelete( uri: string, - resourceExisted: boolean, - options?: DatasetRequestOptions, + dataset: IBulkEditableDataset, ): void { - if (options?.dataset) { - options.dataset.deleteMatches( - undefined, - undefined, - undefined, - namedNode(uri), - ); - deleteResourceRdfFromContainer(uri, options.dataset); - } + dataset.deleteMatches(undefined, undefined, undefined, namedNode(uri)); + deleteResourceRdfFromContainer(uri, dataset); } diff --git a/packages/solid/src/resource/Resource.ts b/packages/solid/src/resource/Resource.ts index 881b9a3..5810428 100644 --- a/packages/solid/src/resource/Resource.ts +++ b/packages/solid/src/resource/Resource.ts @@ -729,7 +729,33 @@ export abstract class Resource extends (EventEmitter as new () => TypedEmitter<{ */ /** - * TODO + * Activates Websocket subscriptions on this resource. Updates, deletions, + * and creations on this resource will be tracked and all changes will be + * relected in LDO's resources and graph. + * + * @param onNotificationError - A callback function if there is an error + * with notifications. + * @returns OpenSubscriptionResult + * + * @example + * ```typescript + * const resource = solidLdoDataset + * .getResource("https://example.com/spiderman"); + * // A listener for if anything about spiderman in the global dataset is + * // changed. Note that this will also listen for any local changes as well + * // as changes to remote resources to which you have notification + * // subscriptions enabled. + * solidLdoDataset.addListener( + * [namedNode("https://example.com/spiderman#spiderman"), null, null, null], + * () => { + * // Triggers when the file changes on the Pod or locally + * console.log("Something changed about SpiderMan"); + * }, + * ); + * + * // Subscribe + * const subscriptionResult = await testContainer.subscribeToNotifications(); + * // ... From there you can ait for a file to be changed on the Pod. */ async subscribeToNotifications( onNotificationError?: (err: Error) => void, @@ -745,7 +771,7 @@ export abstract class Resource extends (EventEmitter as new () => TypedEmitter<{ /** * @internal - * TODO + * Function that triggers whenever a notification is recieved. */ protected async onNotification(message: NotificationMessage): Promise { const objectResource = this.context.solidLdoDataset.getResource( @@ -759,9 +785,10 @@ export abstract class Resource extends (EventEmitter as new () => TypedEmitter<{ case "Delete": case "Remove": // Delete the resource without have to make an additional read request - updateDatasetOnSuccessfulDelete(message.object, true, { - dataset: this.context.solidLdoDataset, - }); + updateDatasetOnSuccessfulDelete( + message.object, + this.context.solidLdoDataset, + ); objectResource.updateWithDeleteSuccess({ type: "deleteSuccess", isError: false, @@ -773,7 +800,14 @@ export abstract class Resource extends (EventEmitter as new () => TypedEmitter<{ } /** - * TODO + * Unsubscribes from changes made to this resource on the Pod + * + * @returns CloseSubscriptionResult + * + * @example + * ```typescript + * resource.unsubscribeFromNotifications() + * ``` */ async unsubscribeFromNotifications(): Promise { const result = await this.notificationSubscription?.close(); diff --git a/packages/solid/src/resource/notifications/NotificationMessage.ts b/packages/solid/src/resource/notifications/NotificationMessage.ts index 7e78153..14e5c2d 100644 --- a/packages/solid/src/resource/notifications/NotificationMessage.ts +++ b/packages/solid/src/resource/notifications/NotificationMessage.ts @@ -1,3 +1,6 @@ +/** + * A message sent from the Pod as a notification + */ export interface NotificationMessage { "@context": string | string[]; id: string; diff --git a/packages/solid/src/resource/notifications/NotificationSubscription.ts b/packages/solid/src/resource/notifications/NotificationSubscription.ts index 1d49e58..87ede6d 100644 --- a/packages/solid/src/resource/notifications/NotificationSubscription.ts +++ b/packages/solid/src/resource/notifications/NotificationSubscription.ts @@ -15,6 +15,10 @@ export type CloseSubscriptionResult = | UnsubscribeToNotificationSuccess | UnexpectedResourceError; +/** + * @internal + * Abstract class for notification subscription methods. + */ export abstract class NotificationSubscription { protected resource: Resource; protected onNotification: (message: NotificationMessage) => void; @@ -33,6 +37,15 @@ export abstract class NotificationSubscription { this.context = context; } + /** + * @internal + * Opens the subscription + */ abstract open(): Promise; + + /** + * @internal + * Closes the subscription + */ abstract close(): Promise; } diff --git a/packages/solid/src/resource/notifications/results/NotificationErrors.ts b/packages/solid/src/resource/notifications/results/NotificationErrors.ts index 2687b19..70382f7 100644 --- a/packages/solid/src/resource/notifications/results/NotificationErrors.ts +++ b/packages/solid/src/resource/notifications/results/NotificationErrors.ts @@ -1,5 +1,9 @@ import { ResourceError } from "../../../requester/results/error/ErrorResult"; +/** + * Indicates that the requested method for receiving notifications is not + * supported by this Pod. + */ export class UnsupportedNotificationError extends ResourceError { readonly type = "unsupportedNotificationError" as const; }