From b6755128db623d6e11f731c61f69fedb014edca4 Mon Sep 17 00:00:00 2001 From: Jackson Morgan Date: Sat, 29 Mar 2025 11:56:57 -0400 Subject: [PATCH] Some documentation updates --- .../src/NextGraphConnectedPlugin.ts | 7 +-- packages/connected/src/ConnectedContext.ts | 4 ++ packages/connected/src/ConnectedLdoDataset.ts | 47 +++++++++++++++++-- .../src/ConnectedLdoTransactionDataset.ts | 5 +- .../src/util/splitChangesByGraph.d.ts | 5 -- .../connected/src/util/splitChangesByGraph.js | 45 ------------------ .../src/util/splitChangesByGraph.js.map | 1 - 7 files changed, 55 insertions(+), 59 deletions(-) delete mode 100644 packages/connected/src/util/splitChangesByGraph.d.ts delete mode 100644 packages/connected/src/util/splitChangesByGraph.js delete mode 100644 packages/connected/src/util/splitChangesByGraph.js.map diff --git a/packages/connected-nextgraph/src/NextGraphConnectedPlugin.ts b/packages/connected-nextgraph/src/NextGraphConnectedPlugin.ts index b44f0db..ae19e9c 100644 --- a/packages/connected-nextgraph/src/NextGraphConnectedPlugin.ts +++ b/packages/connected-nextgraph/src/NextGraphConnectedPlugin.ts @@ -41,11 +41,12 @@ export const nextgGraphConnectedPlugin: NextGraphConnectedPlugin = { "Graph", // NIKO: Can this always be "data:graph"? "data:graph", - // NIKO: What are the options here again? + // NIKO: What are the options here again? "private" "protected" "public" "protected", - // NIKO: What is this? Should it be changed? + // NIKO: What is this? Should it be changed? lookup what the default store + // is "B381BvfdAFYPBkdhDrsqnMMg5pnJMWJgJbZobZErXZMA", - // NIKO: Can this always be "store"? + // NIKO: Can this always be "store"? yes "store", ); return new NextGraphResource(nuri, context); diff --git a/packages/connected/src/ConnectedContext.ts b/packages/connected/src/ConnectedContext.ts index 7bb6716..92aea64 100644 --- a/packages/connected/src/ConnectedContext.ts +++ b/packages/connected/src/ConnectedContext.ts @@ -2,6 +2,10 @@ import type { ConnectedLdoDataset } from "./ConnectedLdoDataset"; import type { ConnectedPlugin } from "./ConnectedPlugin"; +/** + * Each Plugin comes with a context. This is the aggregate of all those contexts + * It is passed between the various components of the "connected" library + */ export type ConnectedContext< Plugins extends ConnectedPlugin[], > = { diff --git a/packages/connected/src/ConnectedLdoDataset.ts b/packages/connected/src/ConnectedLdoDataset.ts index a3489df..7efe4f3 100644 --- a/packages/connected/src/ConnectedLdoDataset.ts +++ b/packages/connected/src/ConnectedLdoDataset.ts @@ -13,19 +13,55 @@ import type { import { ConnectedLdoTransactionDataset } from "./ConnectedLdoTransactionDataset"; import type { SubjectNode } from "@ldo/rdf-utils"; +/** + * A ConnectedLdoDataset has all the functionality of a LdoDataset with the + * added functionality of keeping track of fetched remote Resources. + * + * It is recommended to use the { @link createConnectedLdoDataset } to + * initialize this class. + * + * @example + * ```typescript + * import { createConnectedLdoDataset } from "@ldo/connected"; + * import { ProfileShapeType } from "./.ldo/profile.shapeTypes.ts" + * + * // ... + * + * const connectedLdoDataset = createConnectedLdoDataset(); + * + * const profileDocument = connectedLdoDataset + * .getResource("https://example.com/profile"); + * await profileDocument.read(); + * + * const profile = connectedLdoDataset + * .using(ProfileShapeType) + * .fromSubject("https://example.com/profile#me"); + * ``` + */ export class ConnectedLdoDataset< Plugins extends ConnectedPlugin[], > extends LdoDataset implements IConnectedLdoDataset { + /** + * @internal + * + * A list of plugins used by this dataset + */ private plugins: Plugins; /** * @internal * - * A mapping between a resource URI and a Solid resource + * A mapping between a resource URI and a resource */ protected resourceMap: Map; + + /** + * @internal + * + * Context for each plugin (usually utilities for authentication) + */ protected context: ConnectedContext; constructor( @@ -47,6 +83,11 @@ export class ConnectedLdoDataset< ); } + /** + * @internal + * + * A helper function to return a plugin based in the plugin name and uri. + */ private getValidPlugin( uri: string, pluginName?: string, @@ -80,7 +121,7 @@ export class ConnectedLdoDataset< * * @example * ```typescript - * const profileDocument = solidLdoDataset + * const profileDocument = connectedLdoDataset * .getResource("https://example.com/profile"); * ``` */ @@ -128,7 +169,7 @@ export class ConnectedLdoDataset< } /** - * Shorthand for solidLdoDataset + * Shorthand for connectedLdoDataset * .usingType(shapeType) * .write(...resources.map((r) => r.uri)) * .fromSubject(subject); diff --git a/packages/connected/src/ConnectedLdoTransactionDataset.ts b/packages/connected/src/ConnectedLdoTransactionDataset.ts index 11ca508..98b420f 100644 --- a/packages/connected/src/ConnectedLdoTransactionDataset.ts +++ b/packages/connected/src/ConnectedLdoTransactionDataset.ts @@ -23,8 +23,9 @@ import type { } from "./results/success/SuccessResult"; /** - * A SolidLdoTransactionDataset has all the functionality of a SolidLdoDataset - * and represents a transaction to the parent SolidLdoDataset. + * A ConnectedLdoTransactionDataset has all the functionality of a + * ConnectedLdoDataset and represents a transaction to the parent + * ConnectedLdoDataset. * * It is recommended to use the `startTransaction` method on a SolidLdoDataset * to initialize this class diff --git a/packages/connected/src/util/splitChangesByGraph.d.ts b/packages/connected/src/util/splitChangesByGraph.d.ts deleted file mode 100644 index ece158f..0000000 --- a/packages/connected/src/util/splitChangesByGraph.d.ts +++ /dev/null @@ -1,5 +0,0 @@ -import type { GraphNode, DatasetChanges } from "@ldo/rdf-utils"; -import type { Quad } from "@rdfjs/types"; -export declare function graphNodeToString(graphNode: GraphNode): string; -export declare function stringToGraphNode(input: string): GraphNode; -export declare function splitChangesByGraph(changes: DatasetChanges): Map>; diff --git a/packages/connected/src/util/splitChangesByGraph.js b/packages/connected/src/util/splitChangesByGraph.js deleted file mode 100644 index 0a63728..0000000 --- a/packages/connected/src/util/splitChangesByGraph.js +++ /dev/null @@ -1,45 +0,0 @@ -"use strict"; -Object.defineProperty(exports, "__esModule", { value: true }); -exports.splitChangesByGraph = exports.stringToGraphNode = exports.graphNodeToString = void 0; -const dataset_1 = require("@ldo/dataset"); -const data_model_1 = require("@rdfjs/data-model"); -function graphNodeToString(graphNode) { - return graphNode.termType === "DefaultGraph" - ? "defaultGraph()" - : graphNode.value; -} -exports.graphNodeToString = graphNodeToString; -function stringToGraphNode(input) { - return input === "defaultGraph()" ? (0, data_model_1.defaultGraph)() : (0, data_model_1.namedNode)(input); -} -exports.stringToGraphNode = stringToGraphNode; -function splitChangesByGraph(changes) { - const changesMap = {}; - changes.added?.forEach((quad) => { - const graphHash = graphNodeToString(quad.graph); - if (!changesMap[graphHash]) { - changesMap[graphHash] = {}; - } - if (!changesMap[graphHash].added) { - changesMap[graphHash].added = (0, dataset_1.createDataset)(); - } - changesMap[graphHash].added?.add((0, data_model_1.quad)(quad.subject, quad.predicate, quad.object, quad.graph)); - }); - changes.removed?.forEach((quad) => { - const graphHash = graphNodeToString(quad.graph); - if (!changesMap[graphHash]) { - changesMap[graphHash] = {}; - } - if (!changesMap[graphHash].removed) { - changesMap[graphHash].removed = (0, dataset_1.createDataset)(); - } - changesMap[graphHash].removed?.add((0, data_model_1.quad)(quad.subject, quad.predicate, quad.object, quad.graph)); - }); - const finalMap = new Map(); - Object.entries(changesMap).forEach(([key, value]) => { - finalMap.set(stringToGraphNode(key), value); - }); - return finalMap; -} -exports.splitChangesByGraph = splitChangesByGraph; -//# sourceMappingURL=splitChangesByGraph.js.map \ No newline at end of file diff --git a/packages/connected/src/util/splitChangesByGraph.js.map b/packages/connected/src/util/splitChangesByGraph.js.map deleted file mode 100644 index a31a8b2..0000000 --- a/packages/connected/src/util/splitChangesByGraph.js.map +++ /dev/null @@ -1 +0,0 @@ -{"version":3,"file":"splitChangesByGraph.js","sourceRoot":"","sources":["splitChangesByGraph.ts"],"names":[],"mappings":";;;AAAA,0CAA6C;AAG7C,kDAAgF;AAQhF,SAAgB,iBAAiB,CAAC,SAAoB;IACpD,OAAO,SAAS,CAAC,QAAQ,KAAK,cAAc;QAC1C,CAAC,CAAC,gBAAgB;QAClB,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC;AACtB,CAAC;AAJD,8CAIC;AAQD,SAAgB,iBAAiB,CAAC,KAAa;IAC7C,OAAO,KAAK,KAAK,gBAAgB,CAAC,CAAC,CAAC,IAAA,yBAAY,GAAE,CAAC,CAAC,CAAC,IAAA,sBAAS,EAAC,KAAK,CAAC,CAAC;AACxE,CAAC;AAFD,8CAEC;AASD,SAAgB,mBAAmB,CACjC,OAA6B;IAE7B,MAAM,UAAU,GAAyC,EAAE,CAAC;IAC5D,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;QAC9B,MAAM,SAAS,GAAG,iBAAiB,CAAC,IAAI,CAAC,KAAkB,CAAC,CAAC;QAC7D,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE;YAC1B,UAAU,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC;SAC5B;QACD,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE;YAChC,UAAU,CAAC,SAAS,CAAC,CAAC,KAAK,GAAG,IAAA,uBAAa,GAAE,CAAC;SAC/C;QACD,UAAU,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,GAAG,CAC9B,IAAA,iBAAU,EAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAClE,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;QAChC,MAAM,SAAS,GAAG,iBAAiB,CAAC,IAAI,CAAC,KAAkB,CAAC,CAAC;QAC7D,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE;YAC1B,UAAU,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC;SAC5B;QACD,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE;YAClC,UAAU,CAAC,SAAS,CAAC,CAAC,OAAO,GAAG,IAAA,uBAAa,GAAE,CAAC;SACjD;QACD,UAAU,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,GAAG,CAChC,IAAA,iBAAU,EAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAClE,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAmC,CAAC;IAC5D,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;QAClD,QAAQ,CAAC,GAAG,CAAC,iBAAiB,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IACH,OAAO,QAAQ,CAAC;AAClB,CAAC;AAnCD,kDAmCC"} \ No newline at end of file