@oxilite/common 0.1.0 → 0.2.2

package/README.md

@@ -1,5 +1,52 @@
+<p align="center">
+  <a href="https://oxilitedb.com"><img src="https://raw.githubusercontent.com/Volland/oxilite/main/site/assets/logo.png" alt="oxilite" width="120"></a>
+</p>
+
 # @oxilite/common
 
-RDF/JS terms (`DataFactory`, `NamedNode`, `Literal`, `Quad`…), JSON conversions and result types shared by [`@oxilite/node`](https://www.npmjs.com/package/@oxilite/node) and [`@oxilite/d1`](https://www.npmjs.com/package/@oxilite/d1). You normally get it through one of those packages.
+[![npm](https://img.shields.io/npm/v/@oxilite/common.svg)](https://www.npmjs.com/package/@oxilite/common) [![license](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](https://github.com/Volland/oxilite#license)
+
+**RDF/JS terms and the shared TypeScript types of oxilite**, used by [`@oxilite/node`](https://www.npmjs.com/package/@oxilite/node) and [`@oxilite/d1`](https://www.npmjs.com/package/@oxilite/d1).
+
+**[Website](https://oxilitedb.com)** · [npm](https://www.npmjs.com/package/@oxilite/common) · **[Guide and architecture](https://github.com/Volland/oxilite#readme)** · [Changelog and issues](https://github.com/Volland/oxilite/issues)
+
+You rarely install it directly: both packages re-export everything here.
+
+```ts
+import { namedNode, literal, quad, DataFactory, type Term } from "@oxilite/node";   // or "@oxilite/d1"
+
+const q = quad(namedNode("http://example.com/ada"), namedNode("http://example.com/name"), literal("Ada", "en"));
+```
+
+## What is inside
+
+- **RDF/JS terms:** `NamedNode`, `BlankNode`, `Literal` (with language and direction), `DefaultGraph`, `Variable` and `Quad` (also usable as an RDF 1.2 triple term), plus `DataFactory` and its shortcuts `namedNode`, `blankNode`, `literal`, `defaultGraph`, `variable`, `quad`, `triple`. They follow the [RDF/JS data model](https://rdf.js.org/data-model-spec/), so they mix with other RDF/JS libraries.
+- **SPARQL types:** `QueryOptions` (with oxilite's `reasoning` and `include_inferred`), `LoadOptions`, `DumpOptions`, `QueryResult`.
+- **Cypher types:** `CypherValue`, `CypherNode`, `CypherRelationship`, `CypherPath`, `CypherTemporal`, `CypherResult`, `CypherStats` and `CypherOptions` (`base`, `prefixes`, `names`, `multiValue`, `reasoning`, `shapes`…).
+- **JSON-LD and credential types:** `JsonLdOptions`, `CredentialOptions`, `KeyStrategy`, `GraphStrategy`, `StoredDocument`, `DocumentFilter`, `Drift`, `PresentationKeys` and the `JsonLdError` class (with its JSON-LD error `code`).
+- **JSON helpers:** `toJson` / `fromJson` convert terms to and from the JSON form the oxilite core exchanges.
+
+## The oxilite family
+
+oxilite is an Oxigraph-compatible RDF database and SPARQL 1.1 engine that stores its data in SQLite, so it runs anywhere SQLite runs: in-process, on a system or vendor `libsqlite3`, on Cloudflare D1 and in Durable Objects. The same data can be queried with SPARQL and openCypher, reasoned over with RDFS / OWL, and validated with SHACL and ShEx. Read the overview on **[oxilitedb.com](https://oxilitedb.com)** and the full guide in the [main README](https://github.com/Volland/oxilite#readme).
+
+| Package | What it is for |
+|---|---|
+| [`oxilite`](https://crates.io/crates/oxilite) | The store: a drop-in for `oxigraph::store::Store`, plus `AsyncStore` for D1 |
+| [`oxilite-core`](https://crates.io/crates/oxilite-core) | The sans-IO core: term encoding, schema, SPARQL → SQL compiler and planner |
+| [`oxilite-rusqlite`](https://crates.io/crates/oxilite-rusqlite) | In-process backend with a bundled SQLite (the default) |
+| [`oxilite-dylib`](https://crates.io/crates/oxilite-dylib) | Backend that loads your own `libsqlite3` at runtime |
+| [`oxilite-d1`](https://crates.io/crates/oxilite-d1) | Cloudflare D1 backend for Rust Workers |
+| [`oxilite-cypher`](https://crates.io/crates/oxilite-cypher) | openCypher over the same data, OWL- and SHACL-aware |
+| [`oxilite-jsonld`](https://crates.io/crates/oxilite-jsonld) | JSON-LD documents stored verbatim, one named graph each |
+| [`oxilite-vc`](https://crates.io/crates/oxilite-vc) | Verifiable Credentials: stored under their id, indexed, queryable |
+| [`oxilite-reason`](https://crates.io/crates/oxilite-reason) | OWL 2 RL materialization with `reasonable` |
+| [`oxilite-validate`](https://crates.io/crates/oxilite-validate) | SHACL and ShEx validation with rudof |
+| [`oxilite-cli`](https://crates.io/crates/oxilite-cli) | The `oxilite` command and a SPARQL endpoint like `oxigraph serve` |
+| [`@oxilite/node`](https://www.npmjs.com/package/@oxilite/node) | Node.js bindings, API of Oxigraph's JS package |
+| [`@oxilite/d1`](https://www.npmjs.com/package/@oxilite/d1) | Cloudflare D1 and Durable Objects from TypeScript (WebAssembly core) |
+| [`@oxilite/common`](https://www.npmjs.com/package/@oxilite/common) | RDF/JS terms and shared TypeScript types |
+
+## License
 
-See the [oxilite repository](https://github.com/Volland/oxilite) for documentation.
+Dual-licensed under [MIT](https://github.com/Volland/oxilite/blob/main/LICENSE-MIT) or [Apache-2.0](https://github.com/Volland/oxilite/blob/main/LICENSE-APACHE), at your option, like Oxigraph.

package/dist/index.d.ts

@@ -147,4 +147,178 @@ export interface DumpOptions {
 /** Content of `load()`: a string, bytes, or a list of them (like Oxigraph's JS API). */
 export type LoadData = string | Uint8Array | (string | Uint8Array)[];
 export declare function loadDataToString(data: LoadData): string;
+/** A node of the property-graph view of the dataset. */
+export interface CypherNode {
+    type: "node";
+    /** The node's IRI (or `_:label` for a blank node). */
+    id: string;
+    labels: string[];
+    properties: Record<string, CypherValue>;
+}
+/** A relationship: an RDF triple, identified by its reifier when it has one. */
+export interface CypherRelationship {
+    type: "relationship";
+    id: string;
+    relType: string;
+    start: string;
+    end: string;
+    properties: Record<string, CypherValue>;
+}
+export interface CypherPath {
+    type: "path";
+    nodes: CypherNode[];
+    relationships: CypherRelationship[];
+}
+/** A temporal value in its ISO 8601 form (`value`). */
+export interface CypherTemporal {
+    type: "date" | "datetime" | "localdatetime" | "time" | "localtime" | "duration";
+    value: string;
+}
+export type CypherValue = null | boolean | number | string | CypherValue[] | CypherNode | CypherRelationship | CypherPath | CypherTemporal | {
+    [key: string]: CypherValue;
+};
+/** What a statement changed. */
+export interface CypherStats {
+    nodesCreated: number;
+    nodesDeleted: number;
+    relationshipsCreated: number;
+    relationshipsDeleted: number;
+    propertiesSet: number;
+    labelsAdded: number;
+    labelsRemoved: number;
+}
+export interface CypherResult {
+    columns: string[];
+    rows: CypherValue[][];
+    /** Rows as objects keyed by column. */
+    records: Record<string, CypherValue>[];
+    stats: CypherStats;
+}
+/** Options of the Cypher frontend (see `oxilite_cypher::json`). */
+export interface CypherOptions {
+    /** Namespace of labels, relationship types and keys without a prefix (default `urn:oxilite:pg:`). */
+    base?: string;
+    /** Prefixes usable in names: `` :`schema:Person` ``. */
+    prefixes?: Record<string, string>;
+    /** Explicit name → IRI mappings. */
+    names?: Record<string, string>;
+    /** How a property with several RDF values reads: a list (default), its first value, or an error. */
+    multiValue?: "list" | "first" | "error";
+    /** Maximum hops of an unbounded variable-length relationship that binds a variable. */
+    varLengthCap?: number;
+    /** Maximum depth of an unbounded shortest-path search. */
+    shortestPathCap?: number;
+    /** Check writes against the SHACL shapes of the dataset (default true). */
+    shapes?: boolean;
+    /** Give created nodes an `rdf:type rdfs:Resource` triple (default true). */
+    nodeMarker?: boolean;
+    /** Entailment for matching: `"rdfs"` or `"owl-ql"` make labels follow class hierarchies. */
+    reasoning?: "none" | "rdfs" | "owl-ql";
+    useDefaultGraphAsUnion?: boolean;
+}
+/** Output of a Cypher job (`kind: "cypher"`). */
+export interface CypherOutput {
+    kind: "cypher";
+    columns: string[];
+    rows: CypherValue[][];
+    stats: CypherStats;
+}
+export declare function cypherResult(out: CypherOutput): CypherResult;
+/** Where a document's key comes from. */
+export type KeyStrategy = "id" | "contentHash" | "explicit" | {
+    pointer: string;
+};
+/** Which graph a document's triples go to: the key itself (default), an IRI template with `{key}`, one fixed graph, or the default graph. */
+export type GraphStrategy = "key" | "default" | {
+    template: string;
+} | {
+    fixed: string;
+};
+/** Options of a JSON-LD document handle. */
+export interface JsonLdOptions {
+    /** Default `"id"`: the top-level `@id` / `id`. */
+    key?: KeyStrategy;
+    /** When the key strategy finds nothing: fail (default for documents) or use `urn:oxilite:doc:sha256:<hex>` (default for credentials). */
+    onMissingKey?: "reject" | "contentHash";
+    /** Default `"key"`: one named graph per document, named after its key. */
+    graph?: GraphStrategy;
+    /** Base IRI for relative IRIs in documents. */
+    baseIri?: string;
+    rdfDirection?: "i18n-datatype" | "compound-literal";
+    processingMode?: "json-ld-1.0" | "json-ld-1.1";
+    /** Contexts available in memory: IRI → context document. */
+    contexts?: Record<string, object | string>;
+    /** Fetch unknown remote contexts over HTTP (Node only; default false: no network access). */
+    network?: boolean;
+    /** Persist fetched contexts in the store, so later loads work offline. */
+    cacheFetched?: boolean;
+    /** Metadata indexes created with the tables (all default true). */
+    indexes?: {
+        issuer?: boolean;
+        subject?: boolean;
+        validUntil?: boolean;
+    };
+}
+/** Options of a credentials handle. */
+export interface CredentialOptions extends JsonLdOptions {
+    /** Also store each credential embedded in a presentation on its own (default true). */
+    embedCredentials?: boolean;
+}
+/** A stored document (or credential). */
+export interface StoredDocument {
+    key: string;
+    /** The graph its default-graph triples were written to. */
+    graph: Term;
+    /** The JSON exactly as it was stored. */
+    json: string;
+    /** Hex SHA-256 of `json`. */
+    sha256: string;
+    /** `jsonld`, or `vc1` / `vc2` / `vp1` / `vp2` for credentials and presentations. */
+    profile: string;
+    issuer: string | null;
+    subject: string | null;
+    types: string[];
+    validFrom: Date | null;
+    validUntil: Date | null;
+    /** Keys of the credentials a presentation embeds. */
+    refs: string[];
+    storedAt: Date;
+}
+/** Metadata filter of `find`. */
+export interface DocumentFilter {
+    issuer?: string;
+    subject?: string;
+    /** One value of the `type` array. */
+    type?: string;
+    /** Valid at this instant (validFrom ≤ t < validUntil; open ends allowed). */
+    validAt?: Date | number;
+    profile?: string;
+    /** Keyset paging: keys after this one. */
+    after?: string;
+    limit?: number;
+}
+/** A document whose graphs differ from a fresh conversion of its JSON. */
+export interface Drift {
+    key: string;
+    missing: number;
+    extra: number;
+}
+/** Keys written by `putPresentation`. */
+export interface PresentationKeys {
+    key: string;
+    credentials: string[];
+}
+/** A JSON-LD or credential error; `code` is the JSON-LD error code (e.g. `invalid local context`) or `missing-key`, `invalid-graph-name`, `graph-owned`, `document-too-large`, `invalid`, `json`, `store`. */
+export declare class JsonLdError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Rethrows an error of the core's JSON-LD operations as a `JsonLdError`. */
+export declare function jsonLdError(e: unknown): unknown;
+/** A stored document from the core's JSON (epoch seconds become `Date`s). */
+export declare function storedDocument(j: Record<string, unknown> | null): StoredDocument | null;
+/** A filter in the core's JSON form. */
+export declare function filterJson(f: DocumentFilter): Record<string, unknown>;
+/** A document argument: JSON text is stored verbatim, objects are serialized. */
+export declare function documentText(doc: string | object): string;
 export {};

package/dist/index.js

@@ -209,3 +209,63 @@ export function loadDataToString(data) {
     const one = (d) => (typeof d === "string" ? d : new TextDecoder().decode(d));
     return Array.isArray(data) ? data.map(one).join("\n") : one(data);
 }
+export function cypherResult(out) {
+    return {
+        columns: out.columns,
+        rows: out.rows,
+        records: out.rows.map((row) => Object.fromEntries(out.columns.map((c, i) => [c, row[i] ?? null]))),
+        stats: out.stats,
+    };
+}
+/** A JSON-LD or credential error; `code` is the JSON-LD error code (e.g. `invalid local context`) or `missing-key`, `invalid-graph-name`, `graph-owned`, `document-too-large`, `invalid`, `json`, `store`. */
+export class JsonLdError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "JsonLdError";
+        this.code = code;
+    }
+}
+/** Rethrows an error of the core's JSON-LD operations as a `JsonLdError`. */
+export function jsonLdError(e) {
+    const message = e instanceof Error ? e.message : String(e);
+    const at = message.indexOf("oxilite-jsonld:");
+    if (at < 0)
+        return e;
+    try {
+        const { code, message: m } = JSON.parse(message.slice(at + "oxilite-jsonld:".length));
+        return new JsonLdError(code, m);
+    }
+    catch {
+        return e;
+    }
+}
+/** A stored document from the core's JSON (epoch seconds become `Date`s). */
+export function storedDocument(j) {
+    if (!j)
+        return null;
+    const date = (v) => (typeof v === "number" ? new Date(v * 1000) : null);
+    return {
+        key: j.key,
+        graph: fromJson(j.graph),
+        json: j.json,
+        sha256: j.sha256,
+        profile: j.profile,
+        issuer: j.issuer ?? null,
+        subject: j.subject ?? null,
+        types: j.types ?? [],
+        validFrom: date(j.validFrom),
+        validUntil: date(j.validUntil),
+        refs: j.refs ?? [],
+        storedAt: date(j.storedAt),
+    };
+}
+/** A filter in the core's JSON form. */
+export function filterJson(f) {
+    const t = f.validAt;
+    return { ...f, validAt: t === undefined ? undefined : (t instanceof Date ? t.getTime() : t) / 1000 };
+}
+/** A document argument: JSON text is stored verbatim, objects are serialized. */
+export function documentText(doc) {
+    return typeof doc === "string" ? doc : JSON.stringify(doc);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxilite/common",
-  "version": "0.1.0",
+  "version": "0.2.2",
   "description": "RDF/JS terms and result conversion shared by the oxilite JavaScript packages",
   "license": "MIT OR Apache-2.0",
   "type": "module",
@@ -17,15 +17,15 @@
     "url": "git+https://github.com/Volland/oxilite.git",
     "directory": "packages/common"
   },
-  "homepage": "https://github.com/Volland/oxilite#readme",
+  "homepage": "https://oxilitedb.com",
   "bugs": "https://github.com/Volland/oxilite/issues",
   "author": "Volodymyr Pavlyshyn",
   "keywords": [
     "rdf",
+    "rdfjs",
     "sparql",
-    "sqlite",
-    "oxigraph",
-    "rdfjs"
+    "cypher",
+    "oxilite"
   ],
   "publishConfig": {
     "access": "public"