PROD4POD-1929 - Update PolyIn docs

platform/feature-api/api/src/poly-in.ts

@@ -1,7 +1,8 @@
 import * as RDFJS from "rdf-js";
 
 /**
- * A _matcher_ specifies a filter for querying the Pod store.
+ * A matcher for querying data via [[PolyIn]]. Any property can be left
+ * unspecified.
  */
 export interface Matcher {
     graph: RDFJS.Quad_Graph;
@@ -11,84 +12,61 @@ export interface Matcher {
 }
 
 /**
- * `PolyIn` specifies the interaction of the Feature with the Pod store. It is concerned with creating and manipulating
- * RDF triples according to the [RDFJS](http://rdf.js.org/) specification.
+ * `PolyIn`, mysteriously named for historical reasons, offers access to the
+ * polyPod's internal triplestore through an API that follows the
+ * [RDFJS](http://rdf.js.org/) specification.
  *
- * Features _must_ use the [[Pod.dataFactory]] to create any RDF term they intend to pass to the interface, e.g. for
- * querying and storing, or alternatively re-use RDF terms that have been obtained through PolyIn via other means. It is
- * not allowed to use other data factory implementations.
+ * To create RDF terms that can be passed to `PolyIn`, use
+ * [[Pod.dataFactory]]. Please note that blank nodes, variables, or graphs other
+ * than the default graph are not reliably supported across all platforms and
+ * therefore best avoided.
  *
- * Features _may_ rely on the convention that all RDF triples stored in the Pod are associated with the default graph.
- * In other words, when querying for quads, for all returned quads, the expression `q.graph.equals(factory.defaultGraph())`
- * will hold true. Conversely, Features _should_ only attempt to store quads with the default graph in the Pod, since
- * storage is otherwise not guaranteed.
+ * @see [[PolyOut]] for storing larger amounts of data.
+ * @see [[Triplestore]] for an experimental, more adequately named, replacement
+ * for `PolyIn`.
  *
- * The Pod may impose additional restrictions on the shape of RDF terms that may be stored or queried, for example
- * access control based on IRIs. The Pod may also store additional metadata that is not reified in the RDF data model,
- * e.g. timestamps and origin of read or write access for the purpose of auditing. Features _should not_ confuse empty
- * queries with lack of data, as query results may additionally be filtered.
- *
- * Using blank nodes or variables in any position results in implementation-defined behaviour and should not be relied
- * on, except for internal purposes of the Feature.
  */
+
 export interface PolyIn {
     /**
-     * Queries the Pod for triples matching the given filter. For each property ([[Matcher.subject]],
-     * [[Matcher.predicate]], [[Matcher.object]]) that is specified in the argument, the result set is narrowed to only
-     * contain triples that match the property exactly.
-     *
-     * For example, when querying the store as follows:
-     *
-     * ```
-     * const results = await polyIn.match({
-     *     subject: factory.namedNode("http://example.org")
-     * })
-     * ```
-     *
-     * ... the result is guaranteed to only contain triples with the subject IRI `http://example.org`.
+     * Adds a quad.
      *
-     * Features cannot rely on obtaining a complete view of the data using this method. The results may only reflect a
-     * filtered subset due to e.g. access restrictions or incomplete synchronization across multiple machines.
-     * @param {Partial<Matcher>} matcher - a [[Matcher]] where any property may be left unspecified
-     * @returns {Array.<Quad>} - A set of triples that conform to the specified [[Matcher]] as an array of [[Quad]]s.
+     * @param quad - The quad to store.
      */
-    match(matcher: Partial<Matcher>): Promise<RDFJS.Quad[]>;
+    add(quad: RDFJS.Quad): Promise<void>;
 
     /**
-     * It adds the [[QuadStore]] passed.
-     * Instructs the Pod to add a triple to the store. Successful storage is not guaranteed, as that may be contingent
-     * on other constraints, e.g. access restrictions or synchronization across multiple machines.
-     *
-     * In general, (synchronous) storage errors _should_ be propagated by the Pod to the Feature, resulting in this
-     * method throwing an exception or returning a failed promise. Causes for this include, but are not limited to:
-     *
-     * - the triple is malformed, e.g. not using the default graph
-     * - internal storage error, e.g. disk not writable
-     * - permission violation
-     *
-     * Failures that are handed to the Feature should be handled by the Feature, for example by providing a fallback
-     * option or some form of UI to inform the user of the failure. Other errors are handled by the Pod directly, for
-     * example failure of synchronization across multiple devices.
+     * Deletes a quad.
      *
-     * @param {Quad} quad - The quad triple that should be stored in the Pod
-     * @returns {void}
+     * @param quad - The quad to delete.
      */
-    add(quad: RDFJS.Quad): Promise<void>;
+    delete(quad: RDFJS.Quad): Promise<void>;
 
     /**
-     * Deletes the indicated triples [Quad]].
+     * Checks whether a specific quad has been stored.
      *
-     * @param  {Quad} quad - the triple [[Quad]] that should be removed from the Pod
-     * @returns {void}
+     * @param quad - The quad to look for.
+     * @returns `true` if it exists, otherwise `false`.
      */
-    delete(quad: RDFJS.Quad): Promise<void>;
+    has(quad: RDFJS.Quad): Promise<boolean>;
 
     /**
-     * Checks whether the set of triple (called quads because they include the graph or namespace)
-     * is included in the pod. Returns true if they do.
+     * Queries for quads matching the given matcher.
      *
-     * @param {Quad} quad - the triple to check for in the Pod
-     * @returns a Promise that will be resolved to a boolean.
+     * For each property specified in the matcher, the result set is
+     * narrowed to only contain quads that match it exactly.
+     *
+     * For example, the following query only returns quads with the subject
+     * IRI `http://example.org`:
+     *
+     * ```
+     * const results = await polyIn.match({
+     *     subject: dataFactory.namedNode("http://example.org")
+     * })
+     * ```
+     *
+     * @param matcher - The matcher.
+     * @returns A list of quads that conform to the specified matcher.
      */
-    has(quad: RDFJS.Quad): Promise<boolean>;
+    match(matcher: Partial<Matcher>): Promise<RDFJS.Quad[]>;
 }