Documentation for @ldo/react

main
Jackson Morgan 5 months ago
parent b9b15c9c09
commit c1fa37da98
  1. 46
      packages/react/src/createLdoReactMethods.tsx
  2. 52
      packages/react/src/methods/useLdo.ts
  3. 9
      packages/react/src/methods/useMatchObject.ts
  4. 9
      packages/react/src/methods/useMatchSubject.ts
  5. 8
      packages/react/src/methods/useResource.ts
  6. 9
      packages/react/src/methods/useSubject.ts
  7. 8
      packages/react/src/methods/useSubscribeToResource.ts
  8. 6
      packages/react/src/util/TrackingSetProxy.ts
  9. 6
      packages/react/src/util/TrackingSubjectProxy.ts
  10. 5
      packages/react/src/util/useTrackingProxy.ts

@ -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 <p>loading</p>;
*
* return (
* <ul>
* {post.publisher.map((publisher) => {
* return <li key={publisher["@id"]}>{publisher["@id"]}</li>;
* })}
* </ul>
* );
* };
* ```
*/
export function createLdoReactMethods<
Plugins extends ConnectedPlugin<any, any, any, any>[],
>(plugins: Plugins) {

@ -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<Plugins extends ConnectedPlugin[]> {
/**
* A ConnectedLdoDataset
*/
dataset: ConnectedLdoDataset<Plugins>;
/**
* 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<Plugins>["getResource"];
/**
* Sets conetext for a specific plugin
*
* @param pluginName - the name of the plugin
* @param context - the context for this specific plugin
*/
setContext: ConnectedLdoDataset<Plugins>["setContext"];
/**
* Gets a linked data object based on the subject
*/
getSubject<Type extends LdoBase>(
shapeType: ShapeType<Type>,
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<Type extends LdoBase>(
shapeType: ShapeType<Type>,
subject: string | SubjectNode,
resource: Plugins[number]["types"]["resource"],
...additionalResources: Plugins[number]["types"]["resource"][]
): Type;
/**
* Returns a writable LinkedDataObject given a linked data object
*/
changeData<Type extends LdoBase>(
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<ConnectedLdoTransactionDataset<Plugins>["commitToRemote"]>;
}
/**
* @internal
* Creates the useLdoHook
*/
export function createUseLdo<Plugins extends ConnectedPlugin[]>(
dataset: ConnectedLdoDataset<Plugins>,
) {
return (): UseLdoMethods<Plugins> => ({
const toReturn = {
dataset,
/**
* Gets a resource
@ -94,5 +139,8 @@ export function createUseLdo<Plugins extends ConnectedPlugin[]>(
) as ConnectedLdoTransactionDataset<Plugins>;
return inputDataset.commitToRemote();
},
});
};
return function useLdo(): UseLdoMethods<Plugins> {
return toReturn;
};
}

@ -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<Plugins extends ConnectedPlugin[]>(
dataset: ConnectedLdoDataset<Plugins>,
) {
/**
* Returns an array of matching items and triggers a rerender when that data
* is updated.
*/
return function useMatchObject<Type extends LdoBase>(
shapeType: ShapeType<Type>,
subject?: QuadMatch[0] | string,

@ -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<Plugins extends ConnectedPlugin[]>(
dataset: ConnectedLdoDataset<Plugins>,
) {
/**
* Returns an array of matching linked data objects. Triggers a rerender if
* the data is updated.
*/
return function useMatchSubject<Type extends LdoBase>(
shapeType: ShapeType<Type>,
predicate?: QuadMatch[1] | string,

@ -32,9 +32,17 @@ export type useResourceType<Plugins extends ConnectedPlugin[]> = {
): GetResourceReturnType<Plugin, UriType> | undefined;
};
/**
* @internal
*
* Creates a useResource function.
*/
export function createUseResource<Plugins extends ConnectedPlugin[]>(
dataset: ConnectedLdoDataset<Plugins>,
): useResourceType<Plugins> {
/**
* Returns a resource and triggers a rerender if that resource is updated.
*/
return function useResource<
Name extends Plugins[number]["name"],
Plugin extends Extract<Plugins[number], { name: Name }>,

@ -22,9 +22,18 @@ export type useSubjectType = {
): Type | undefined;
};
/**
* @internal
*
* Creates a useSubject function.
*/
export function createUseSubject<Plugins extends ConnectedPlugin[]>(
dataset: ConnectedLdoDataset<Plugins>,
): useSubjectType {
/**
* Returns a Linked Data Object based on the provided subject. Triggers a
* rerender if the data is udpated.
*/
return function useSubject<Type extends LdoBase>(
shapeType: ShapeType<Type>,
subject?: string | SubjectNode,

@ -1,9 +1,17 @@
import { useEffect, useRef } from "react";
import type { ConnectedLdoDataset, ConnectedPlugin } from "@ldo/connected";
/**
* @internal
*
* Creates a useSubscribeToResource function.
*/
export function createUseSubscribeToResource<Plugins extends ConnectedPlugin[]>(
dataset: ConnectedLdoDataset<Plugins>,
) {
/**
* Starts a subscription to a resource.
*/
return function useSubscribeToResource(...uris: string[]): void {
const currentlySubscribed = useRef<Record<string, string>>({});
useEffect(() => {

@ -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,

@ -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,

@ -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<Type extends LdoBase, ReturnType>(
shapeType: ShapeType<Type>,
createLdo: (builder: LdoBuilder<Type>) => ReturnType,

Loading…
Cancel
Save