diff --git a/packages/react/src/createLdoReactMethods.tsx b/packages/react/src/createLdoReactMethods.tsx
index 57e3f2d..eee6e21 100644
--- a/packages/react/src/createLdoReactMethods.tsx
+++ b/packages/react/src/createLdoReactMethods.tsx
@@ -10,6 +10,52 @@ import { createUseResource } from "./methods/useResource";
import { createUseSubject } from "./methods/useSubject";
import { createUseSubscribeToResource } from "./methods/useSubscribeToResource";
+/**
+ * A function that creates all common react functions given specific plugin.
+ *
+ * @example
+ * `methods.ts`
+ * ```tyepscript
+ * import { solidConnectedPlugin } from "@ldo/connected-solid";
+ * import { nextGraphConnectedPlugin } from "@ldo/connected-nextgraph";
+ * import { createLdoReactMethods } from "@ldo/react";
+ *
+ * // Export the results to be used in the reset of the application
+ * export const {
+ * dataset,
+ * useLdo,
+ * useMatchObject,
+ * useMatchSubject,
+ * useResource,
+ * useSubject,
+ * useSubscribeToResource,
+ * } = createLdoReactMethods([
+ * solidConnectedPlugin,
+ * nextGraphConnectedPlugin
+ * ]);
+ * ```
+ *
+ * `App.tsx`
+ * ```typescript
+ * import react, { FunctionComponent } from "react";
+ * import { PostShShapeType } from "./.ldo/posts.shapeType.ts";
+ * import { useResource, useSubject } from "./methods.ts";
+ *
+ * const UseSubjectTest: FunctionComponent = () => {
+ * const resource = useResource(SAMPLE_DATA_URI);
+ * const post = useSubject(PostShShapeType, `${SAMPLE_DATA_URI}#Post1`);
+ * if (resource.isLoading() || !post) return
loading
;
+ *
+ * return (
+ *
+ * {post.publisher.map((publisher) => {
+ * return - {publisher["@id"]}
;
+ * })}
+ *
+ * );
+ * };
+ * ```
+ */
export function createLdoReactMethods<
Plugins extends ConnectedPlugin[],
>(plugins: Plugins) {
diff --git a/packages/react/src/methods/useLdo.ts b/packages/react/src/methods/useLdo.ts
index 78a6c79..de31a3f 100644
--- a/packages/react/src/methods/useLdo.ts
+++ b/packages/react/src/methods/useLdo.ts
@@ -7,34 +7,79 @@ import {
import { getDataset, type LdoBase, type ShapeType } from "@ldo/ldo";
import type { SubjectNode } from "@ldo/rdf-utils";
+/**
+ * The methods returned by useLdo
+ */
export interface UseLdoMethods {
+ /**
+ * A ConnectedLdoDataset
+ */
dataset: ConnectedLdoDataset;
+ /**
+ * Retireves a representation of a Resource at the given URI. This resource
+ * represents the current state of the resource: whether it is currently
+ * fetched or in the process of fetching as well as some information about it.
+ *
+ * @param uri - the URI of the resource
+ * @param pluginName - optionally, force this function to choose a specific
+ * plugin to use rather than perform content negotiation.
+ *
+ * @returns a Resource
+ */
getResource: ConnectedLdoDataset["getResource"];
+ /**
+ * Sets conetext for a specific plugin
+ *
+ * @param pluginName - the name of the plugin
+ * @param context - the context for this specific plugin
+ */
setContext: ConnectedLdoDataset["setContext"];
+ /**
+ * Gets a linked data object based on the subject
+ */
getSubject(
shapeType: ShapeType,
subject: string | SubjectNode,
): Type;
+ /**
+ * Shorthand for connectedLdoDataset
+ * .usingType(shapeType)
+ * .write(...resources.map((r) => r.uri))
+ * .fromSubject(subject);
+ * @param shapeType - The shapetype to represent the data
+ * @param subject - A subject URI
+ * @param resources - The resources changes to should written to
+ */
createData(
shapeType: ShapeType,
subject: string | SubjectNode,
resource: Plugins[number]["types"]["resource"],
...additionalResources: Plugins[number]["types"]["resource"][]
): Type;
+ /**
+ * Returns a writable LinkedDataObject given a linked data object
+ */
changeData(
input: Type,
resource: Plugins[number]["types"]["resource"],
...additionalResources: Plugins[number]["types"]["resource"][]
): Type;
+ /**
+ * Commits the data of a writable Linke Data Object back to the remote.
+ */
commitData(
input: LdoBase,
): ReturnType["commitToRemote"]>;
}
+/**
+ * @internal
+ * Creates the useLdoHook
+ */
export function createUseLdo(
dataset: ConnectedLdoDataset,
) {
- return (): UseLdoMethods => ({
+ const toReturn = {
dataset,
/**
* Gets a resource
@@ -94,5 +139,8 @@ export function createUseLdo(
) as ConnectedLdoTransactionDataset;
return inputDataset.commitToRemote();
},
- });
+ };
+ return function useLdo(): UseLdoMethods {
+ return toReturn;
+ };
}
diff --git a/packages/react/src/methods/useMatchObject.ts b/packages/react/src/methods/useMatchObject.ts
index a77ff8a..4934df6 100644
--- a/packages/react/src/methods/useMatchObject.ts
+++ b/packages/react/src/methods/useMatchObject.ts
@@ -5,9 +5,18 @@ import { useCallback } from "react";
import { useTrackingProxy } from "../util/useTrackingProxy";
import type { ConnectedLdoDataset, ConnectedPlugin } from "@ldo/connected";
+/**
+ * @internal
+ *
+ * Creates a useMatchObject function
+ */
export function createUseMatchObject(
dataset: ConnectedLdoDataset,
) {
+ /**
+ * Returns an array of matching items and triggers a rerender when that data
+ * is updated.
+ */
return function useMatchObject(
shapeType: ShapeType,
subject?: QuadMatch[0] | string,
diff --git a/packages/react/src/methods/useMatchSubject.ts b/packages/react/src/methods/useMatchSubject.ts
index 0adac52..9b0b20b 100644
--- a/packages/react/src/methods/useMatchSubject.ts
+++ b/packages/react/src/methods/useMatchSubject.ts
@@ -5,9 +5,18 @@ import { useCallback } from "react";
import { useTrackingProxy } from "../util/useTrackingProxy";
import type { ConnectedLdoDataset, ConnectedPlugin } from "@ldo/connected";
+/**
+ * @internal
+ *
+ * Creates a useMatchSubject function.
+ */
export function createUseMatchSubject(
dataset: ConnectedLdoDataset,
) {
+ /**
+ * Returns an array of matching linked data objects. Triggers a rerender if
+ * the data is updated.
+ */
return function useMatchSubject(
shapeType: ShapeType,
predicate?: QuadMatch[1] | string,
diff --git a/packages/react/src/methods/useResource.ts b/packages/react/src/methods/useResource.ts
index f6d0cf3..d17420d 100644
--- a/packages/react/src/methods/useResource.ts
+++ b/packages/react/src/methods/useResource.ts
@@ -32,9 +32,17 @@ export type useResourceType = {
): GetResourceReturnType | undefined;
};
+/**
+ * @internal
+ *
+ * Creates a useResource function.
+ */
export function createUseResource(
dataset: ConnectedLdoDataset,
): useResourceType {
+ /**
+ * Returns a resource and triggers a rerender if that resource is updated.
+ */
return function useResource<
Name extends Plugins[number]["name"],
Plugin extends Extract,
diff --git a/packages/react/src/methods/useSubject.ts b/packages/react/src/methods/useSubject.ts
index 2969983..8f1768f 100644
--- a/packages/react/src/methods/useSubject.ts
+++ b/packages/react/src/methods/useSubject.ts
@@ -22,9 +22,18 @@ export type useSubjectType = {
): Type | undefined;
};
+/**
+ * @internal
+ *
+ * Creates a useSubject function.
+ */
export function createUseSubject(
dataset: ConnectedLdoDataset,
): useSubjectType {
+ /**
+ * Returns a Linked Data Object based on the provided subject. Triggers a
+ * rerender if the data is udpated.
+ */
return function useSubject(
shapeType: ShapeType,
subject?: string | SubjectNode,
diff --git a/packages/react/src/methods/useSubscribeToResource.ts b/packages/react/src/methods/useSubscribeToResource.ts
index c9b589e..f2af1ca 100644
--- a/packages/react/src/methods/useSubscribeToResource.ts
+++ b/packages/react/src/methods/useSubscribeToResource.ts
@@ -1,9 +1,17 @@
import { useEffect, useRef } from "react";
import type { ConnectedLdoDataset, ConnectedPlugin } from "@ldo/connected";
+/**
+ * @internal
+ *
+ * Creates a useSubscribeToResource function.
+ */
export function createUseSubscribeToResource(
dataset: ConnectedLdoDataset,
) {
+ /**
+ * Starts a subscription to a resource.
+ */
return function useSubscribeToResource(...uris: string[]): void {
const currentlySubscribed = useRef>({});
useEffect(() => {
diff --git a/packages/react/src/util/TrackingSetProxy.ts b/packages/react/src/util/TrackingSetProxy.ts
index 9c34347..cf3e74f 100644
--- a/packages/react/src/util/TrackingSetProxy.ts
+++ b/packages/react/src/util/TrackingSetProxy.ts
@@ -2,6 +2,12 @@ import { createNewSetProxy, type SetProxy } from "@ldo/jsonld-dataset-proxy";
import type { TrackingProxyContext } from "./TrackingProxyContext";
import type { QuadMatch } from "@ldo/rdf-utils";
+/**
+ * @internal
+ *
+ * Creates a tracking proxy, a proxy that tracks the fields that have been
+ * accessed.
+ */
export function createTrackingSetProxy(
proxyContext: TrackingProxyContext,
quadMatch: QuadMatch,
diff --git a/packages/react/src/util/TrackingSubjectProxy.ts b/packages/react/src/util/TrackingSubjectProxy.ts
index 54fa5fe..74154bf 100644
--- a/packages/react/src/util/TrackingSubjectProxy.ts
+++ b/packages/react/src/util/TrackingSubjectProxy.ts
@@ -7,6 +7,12 @@ import type { BlankNode, NamedNode } from "@rdfjs/types";
import type { TrackingProxyContext } from "./TrackingProxyContext";
import { namedNode } from "@rdfjs/data-model";
+/**
+ * @internal
+ *
+ * Creates a tracking proxy for a single value, a proxy that tracks the fields
+ * that have been accessed.
+ */
export function createTrackingSubjectProxy(
proxyContext: TrackingProxyContext,
node: NamedNode | BlankNode,
diff --git a/packages/react/src/util/useTrackingProxy.ts b/packages/react/src/util/useTrackingProxy.ts
index 64793e0..33d39e1 100644
--- a/packages/react/src/util/useTrackingProxy.ts
+++ b/packages/react/src/util/useTrackingProxy.ts
@@ -8,6 +8,11 @@ import { useCallback, useEffect, useMemo, useState } from "react";
import { TrackingProxyContext } from "./TrackingProxyContext";
import { defaultGraph } from "@rdfjs/data-model";
+/**
+ * @internal
+ *
+ * A hook for tracking proxies
+ */
export function useTrackingProxy(
shapeType: ShapeType,
createLdo: (builder: LdoBuilder) => ReturnType,