diff --git a/packages/connected/src/linkTraversal/ResourceLinkQuery.ts b/packages/connected/src/linkTraversal/ResourceLinkQuery.ts index 947a03f..544ece2 100644 --- a/packages/connected/src/linkTraversal/ResourceLinkQuery.ts +++ b/packages/connected/src/linkTraversal/ResourceLinkQuery.ts @@ -14,6 +14,33 @@ import { v4 } from "uuid"; import type { nodeEventListener } from "@ldo/subscribable-dataset"; import type { Quad } from "@rdfjs/types"; +/** + * Represents a query over multiple datasources and constituting muliple + * resources. + * + * @example + * ```typescript + * import { ProfileShapeType } from "./.ldo/Profile.shapeType.ts"; + * + * // Create a link query + * const linkQuery = ldoDataset + * .usingType(ProfileShapeType) + * .startLinkQuery( + * "http://example.com/profile/card", + * "http://example.com/profile/card#me", + * { + * name: true, + * knows: { + * name: true, + * }, + * }, + * } + * ); + * // Susbscribe to this link query, automaticically updating the dataset when + * // something from the link query is changed. + * await linkQuery.subscribe(); + * ``` + */ export class ResourceLinkQuery< Type extends LdoBase, QueryInput extends LQInput, @@ -34,6 +61,15 @@ export class ResourceLinkQuery< Promise | undefined > = {}; + /** + * @internal + * @param parentDataset The dataset for which this link query is a part + * @param shapeType A ShapeType for the link query to follow + * @param ldoBuilder An LdoBuilder associated with the dataset + * @param startingResource The resource to explore first in the link query + * @param startingSubject The starting point of the link query + * @param linkQueryInput A definition of the link query + */ constructor( protected parentDataset: IConnectedLdoDataset, protected shapeType: ShapeType, @@ -43,6 +79,39 @@ export class ResourceLinkQuery< protected linkQueryInput: QueryInput, ) {} + /** + * Runs this link query, returning the result + * @param options Options for how to run the link query + * @returns A subset of the ShapeType as defined by the LinkQuery + * + * @example + * ``` + * import { ProfileShapeType } from "./.ldo/Profile.shapeType.ts"; + * + * // Create a link query + * const linkQuery = ldoDataset + * .usingType(ProfileShapeType) + * .startLinkQuery( + * "http://example.com/profile/card", + * "http://example.com/profile/card#me", + * { + * name: true, + * knows: { + * name: true, + * }, + * }, + * } + * ); + * // Susbscribe to this link query, automaticically updating the dataset when + * // something from the link query is changed. + * const result = await linkQuery.read(); + * console.log(result.name); + * result.knows.forEach((person) => console.log(person.name)); + * // The following will type-error. Despite "phone" existing on a Profile, + * // it was not covered by the link query. + * console.log(result.phone); + * ``` + */ async run(options?: { reload?: boolean; }): Promise>> { @@ -57,6 +126,42 @@ export class ResourceLinkQuery< return this.fromSubject(); } + /** + * Subscribes to the data defined by the link query, updating the dataset if + * any changes are made. + * @returns An unsubscribeId + * + * @example + * ``` + * import { ProfileShapeType } from "./.ldo/Profile.shapeType.ts"; + * + * // Create a link query + * const linkQuery = ldoDataset + * .usingType(ProfileShapeType) + * .startLinkQuery( + * "http://example.com/profile/card", + * "http://example.com/profile/card#me", + * { + * name: true, + * knows: { + * name: true, + * }, + * }, + * } + * ); + * // Susbscribe to this link query, automaticically updating the dataset when + * // something from the link query is changed. + * const unsubscribeId = await linkQuery.subscribe(); + * + * // Now, let's imagine the following triple was added to + * "http://example.com/profile/card": + * + * Because you're subscribed, the dataset will automatically be updated. + * + * // End subscription + * linkQuery.unsubscribe(unsubscribeId); + * ``` + */ async subscribe(): Promise { const subscriptionId = v4(); this.thisUnsubscribeIds.add(subscriptionId); diff --git a/packages/connected/src/linkTraversal/exploreLinks.ts b/packages/connected/src/linkTraversal/exploreLinks.ts index cb45479..6871dc8 100644 --- a/packages/connected/src/linkTraversal/exploreLinks.ts +++ b/packages/connected/src/linkTraversal/exploreLinks.ts @@ -8,6 +8,9 @@ import { createTrackingProxyBuilder } from "../trackingProxy/createTrackingProxy import type { nodeEventListener } from "@ldo/subscribable-dataset"; import type { Quad } from "@rdfjs/types"; +/** + * @internal + */ interface ExploreLinksOptions { onResourceEncountered?: ( resource: Plugins[number]["types"]["resource"], @@ -16,6 +19,9 @@ interface ExploreLinksOptions { shouldRefreshResources?: boolean; } +/** + * @internal + */ export async function exploreLinks< Type extends LdoBase, Plugins extends ConnectedPlugin[], diff --git a/packages/react/README.md b/packages/react/README.md index 1eb1bbf..f5eff87 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -127,6 +127,7 @@ Hooks - [useMatchSubject](https://ldo.js.org/latest/api/react/useMatchSubject/) - [useMatchObject](https://ldo.js.org/latest/api/react/useMatchSubject/) - [useSubscribeToResource](https://ldo.js.org/latest/api/react/useMatchSubject/) + - [useLinkQuery](https://ldo.js.org/latest/api/react/useLinkQuery/) ## Sponsorship This project was made possible by a grant from NGI Zero Entrust via nlnet. Learn more on the [NLnet project page](https://nlnet.nl/project/SolidUsableApps/). diff --git a/packages/solid-react/README.md b/packages/solid-react/README.md index 1458af6..663b5ed 100644 --- a/packages/solid-react/README.md +++ b/packages/solid-react/README.md @@ -20,17 +20,13 @@ Now install the @ldo/solid library npm i @ldo/solid @ldo/solid-react ``` -
- -Manual Installation - +### Manual Installation If you already have generated ShapeTypes, you may install the `@ldo/ldo` and `@ldo/solid` libraries independently. ``` npm i @ldo/ldo @ldo/solid @ldo/solid-react ``` -
## Simple Example @@ -115,18 +111,19 @@ export default App; Providers - - [BrowserSolidLdoProvider](https://ldo.js.org/latest/api/react/BrowserSolidLdoProvider/) - - [SolidLdoProvider](https://ldo.js.org/latest/api/react/SolidLdoProvider/) + - [BrowserSolidLdoProvider](https://ldo.js.org/latest/api/solid-react/BrowserSolidLdoProvider/) + - [SolidLdoProvider](https://ldo.js.org/latest/api/solid-react/SolidLdoProvider/) Hooks - - [useLdo](https://ldo.js.org/latest/api/react/useLdo/) - - [useResource](https://ldo.js.org/latest/api/react/useResource/) - - [useRootContainer](https://ldo.js.org/latest/api/react/useRootContainer/) - - [useSolidAuth](https://ldo.js.org/latest/api/react/useSolidAuth/) - - [useSubject](https://ldo.js.org/latest/api/react/useSubject/) - - [useMatchSubject](https://ldo.js.org/latest/api/react/useMatchSubject/) - - [useMatchObject](https://ldo.js.org/latest/api/react/useMatchSubject/) - - [useSubscribeToResource](https://ldo.js.org/latest/api/react/useMatchSubject/) + - [useLdo](https://ldo.js.org/latest/api/solid-react/useLdo/) + - [useResource](https://ldo.js.org/latest/api/solid-react/useResource/) + - [useRootContainer](https://ldo.js.org/latest/api/solid-react/useRootContainer/) + - [useSolidAuth](https://ldo.js.org/latest/api/solid-react/useSolidAuth/) + - [useSubject](https://ldo.js.org/latest/api/solid-react/useSubject/) + - [useMatchSubject](https://ldo.js.org/latest/api/solid-react/useMatchSubject/) + - [useMatchObject](https://ldo.js.org/latest/api/solid-react/useMatchSubject/) + - [useSubscribeToResource](https://ldo.js.org/latest/api/solid-react/useMatchSubject/) + - [useLinkQUery](https://ldo.js.org/latest/api/solid-react/useLinkQuery/) ## Sponsorship This project was made possible by a grant from NGI Zero Entrust via nlnet. Learn more on the [NLnet project page](https://nlnet.nl/project/SolidUsableApps/).