@noeldemartin/solid-utils 0.1.0 → 0.1.1-next.4e968af69bdec1e90b14bf8107fad4fafd43f952

package/src/helpers/io.ts

@@ -1,6 +1,8 @@
-import { arr, arrayFilter, arrayReplace,objectWithoutEmpty } from '@noeldemartin/utils';
-import { BlankNode as N3BlankNode, Quad as N3Quad, Parser as TurtleParser, Writer as TurtleWriter } from 'n3';
 import md5 from 'md5';
+import { arr, arrayFilter, arrayReplace, objectWithoutEmpty, stringMatchAll, tap } from '@noeldemartin/utils';
+import { BlankNode as N3BlankNode, Quad as N3Quad, Parser as TurtleParser, Writer as TurtleWriter } from 'n3';
+import { fromRDF, toRDF } from 'jsonld';
+import type { JsonLdDocument } from 'jsonld';
 import type { Quad } from 'rdf-js';
 import type { Term as N3Term } from 'n3';
 
@@ -10,9 +12,11 @@ import MalformedSolidDocumentError, { SolidDocumentFormat } from '@/errors/Malfo
 import NetworkRequestError from '@/errors/NetworkRequestError';
 import NotFoundError from '@/errors/NotFoundError';
 import UnauthorizedError from '@/errors/UnauthorizedError';
+import { isJsonLDGraph } from '@/helpers/jsonld';
+import type { JsonLD, JsonLDGraph, JsonLDResource } from '@/helpers/jsonld';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export declare type AnyFetch = (input: any, options?: any) => Promise<any>;
+export declare type AnyFetch = (input: any, options?: any) => Promise<Response>;
 export declare type TypedFetch = (input: RequestInfo, options?: RequestInit) => Promise<Response>;
 export declare type Fetch = TypedFetch | AnyFetch;
 
@@ -40,7 +44,10 @@ async function fetchRawSolidDocument(url: string, fetch: Fetch): Promise<{ body:
         if (error instanceof UnauthorizedError)
             throw error;
 
-        throw new NetworkRequestError(url);
+        if (error instanceof NotFoundError)
+            throw error;
+
+        throw new NetworkRequestError(url, { cause: error });
     }
 }
 
@@ -48,26 +55,23 @@ function normalizeBlankNodes(quads: Quad[]): Quad[] {
     const normalizedQuads = quads.slice(0);
     const quadsIndexes: Record<string, Set<number>> = {};
     const blankNodeIds = arr(quads)
-        .flatMap((quad, index) => {
-            const ids = arrayFilter([
-                quad.object.termType === 'BlankNode' ? quad.object.value : null,
-                quad.subject.termType === 'BlankNode' ? quad.subject.value : null,
-            ]);
-
-            for (const id of ids) {
-                quadsIndexes[id] = quadsIndexes[id] ?? new Set();
-                quadsIndexes[id].add(index);
-            }
-
-            return ids;
-        })
+        .flatMap(
+            (quad, index) => tap(
+                arrayFilter([
+                    quad.object.termType === 'BlankNode' ? quad.object.value : null,
+                    quad.subject.termType === 'BlankNode' ? quad.subject.value : null,
+                ]),
+                ids => ids.forEach(id => (quadsIndexes[id] ??= new Set()).add(index)),
+            ),
+        )
         .filter()
         .unique();
 
     for (const originalId of blankNodeIds) {
+        const quadIndexes = quadsIndexes[originalId] as Set<number>;
         const normalizedId = md5(
-            arr(quadsIndexes[originalId])
-                .map(index => quads[index])
+            arr(quadIndexes)
+                .map(index => quads[index] as Quad)
                 .filter(({ subject: { termType, value } }) => termType === 'BlankNode' && value === originalId)
                 .map(
                     ({ predicate, object }) => object.termType === 'BlankNode'
@@ -78,9 +82,12 @@ function normalizeBlankNodes(quads: Quad[]): Quad[] {
                 .join(),
         );
 
-        for (const index of quadsIndexes[originalId]) {
-            const quad = normalizedQuads[index];
-            const terms: Record<string, N3Term> = { subject: quad.subject as N3Term, object: quad.object as N3Term };
+        for (const index of quadIndexes) {
+            const quad = normalizedQuads[index] as Quad;
+            const terms: Record<string, N3Term> = {
+                subject: quad.subject as N3Term,
+                object: quad.object as N3Term,
+            };
 
             for (const [termName, termValue] of Object.entries(terms)) {
                 if (termValue.termType !== 'BlankNode' || termValue.value !== originalId)
@@ -89,7 +96,15 @@ function normalizeBlankNodes(quads: Quad[]): Quad[] {
                 terms[termName] = new N3BlankNode(normalizedId);
             }
 
-            arrayReplace(normalizedQuads, quad, new N3Quad(terms.subject, quad.predicate as N3Term, terms.object));
+            arrayReplace(
+                normalizedQuads,
+                quad,
+                new N3Quad(
+                    terms.subject as N3Term,
+                    quad.predicate as N3Term,
+                    terms.object as N3Term,
+                ),
+            );
         }
     }
 
@@ -102,7 +117,7 @@ export interface ParsingOptions {
 }
 
 export async function createSolidDocument(url: string, body: string, fetch?: Fetch): Promise<SolidDocument> {
-    fetch = fetch ?? window.fetch;
+    fetch = fetch ?? window.fetch.bind(window);
 
     const statements = await turtleToQuads(body);
 
@@ -122,6 +137,29 @@ export async function fetchSolidDocument(url: string, fetch?: Fetch): Promise<So
     return new SolidDocument(url, statements, headers);
 }
 
+export async function fetchSolidDocumentIfFound(url: string, fetch?: Fetch): Promise<SolidDocument | null> {
+    try {
+        const document = await fetchSolidDocument(url, fetch);
+
+        return document;
+    } catch (error) {
+        if (!(error instanceof NotFoundError))
+            throw error;
+
+        return null;
+    }
+}
+
+export async function jsonldToQuads(jsonld: JsonLD): Promise<Quad[]> {
+    if (isJsonLDGraph(jsonld)) {
+        const graphQuads = await Promise.all(jsonld['@graph'].map(jsonldToQuads));
+
+        return graphQuads.flat();
+    }
+
+    return toRDF(jsonld as JsonLdDocument) as Promise<Quad[]>;
+}
+
 export function normalizeSparql(sparql: string): string {
     const quads = sparqlToQuadsSync(sparql);
 
@@ -135,6 +173,20 @@ export function normalizeSparql(sparql: string): string {
         .join(' ;\n');
 }
 
+export async function quadsToJsonLD(quads: Quad[]): Promise<JsonLDGraph> {
+    const graph = await fromRDF(quads);
+
+    return {
+        '@graph': graph as JsonLDResource[],
+    };
+}
+
+export function quadsToTurtle(quads: Quad[]): string {
+    const writer = new TurtleWriter;
+
+    return writer.quadsToString(quads);
+}
+
 export function quadToTurtle(quad: Quad): string {
     const writer = new TurtleWriter;
 
@@ -155,7 +207,7 @@ export async function sparqlToQuads(
     sparql: string,
     options: Partial<ParsingOptions> = {},
 ): Promise<Record<string, Quad[]>> {
-    const operations = sparql.matchAll(/(\w+) DATA {([^}]+)}/g);
+    const operations = stringMatchAll<3>(sparql, /(\w+) DATA {([^}]+)}/g);
     const quads: Record<string, Quad[]> = {};
 
     await Promise.all([...operations].map(async operation => {
@@ -169,7 +221,7 @@ export async function sparqlToQuads(
 }
 
 export function sparqlToQuadsSync(sparql: string, options: Partial<ParsingOptions> = {}): Record<string, Quad[]> {
-    const operations = sparql.matchAll(/(\w+) DATA {([^}]+)}/g);
+    const operations = stringMatchAll<3>(sparql, /(\w+) DATA {([^}]+)}/g);
     const quads: Record<string, Quad[]> = {};
 
     for (const operation of operations) {
@@ -224,12 +276,16 @@ export function turtleToQuadsSync(turtle: string, options: Partial<ParsingOption
             ? normalizeBlankNodes(quads)
             : quads;
     } catch (error) {
-        throw new MalformedSolidDocumentError(options.documentUrl ?? null, SolidDocumentFormat.Turtle, error.message);
+        throw new MalformedSolidDocumentError(
+            options.documentUrl ?? null,
+            SolidDocumentFormat.Turtle,
+            (error as Error).message ?? '',
+        );
     }
 }
 
 export async function updateSolidDocument(url: string, body: string, fetch?: Fetch): Promise<void> {
-    fetch = fetch ?? window.fetch;
+    fetch = fetch ?? window.fetch.bind(window);
 
     await fetch(url, {
         method: 'PATCH',

package/src/helpers/jsonld.ts

@@ -6,3 +6,7 @@ export type JsonLD = Partial<{
 
 export type JsonLDResource = Omit<JsonLD, '@id'> & { '@id': string };
 export type JsonLDGraph = { '@graph': JsonLDResource[] };
+
+export function isJsonLDGraph(jsonld: JsonLD): jsonld is JsonLDGraph {
+    return '@graph' in jsonld;
+}

package/src/helpers/testing.ts

@@ -1,39 +1,67 @@
-import { pull } from '@noeldemartin/utils';
+import { Error, arrayRemove, pull, stringMatchAll } from '@noeldemartin/utils';
+import type { JsonLD } from '@/helpers/jsonld';
 import type { Quad, Quad_Object } from 'rdf-js';
 
-import { quadToTurtle, sparqlToQuadsSync, turtleToQuadsSync } from './io';
+import { jsonldToQuads, quadToTurtle, quadsToTurtle, sparqlToQuadsSync, turtleToQuadsSync } from './io';
 
-const patternRegExps: Record<string, RegExp> = {};
+let patternsRegExpsIndex: Record<string, RegExp> = {};
+const builtInPatterns: Record<string, string> = {
+    '%uuid%': '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}',
+};
+
+class ExpectedQuadAssertionError extends Error {
+
+    constructor(public readonly expectedQuad: Quad) {
+        super(`Couldn't find the following triple: ${quadToTurtle(expectedQuad)}`);
+    }
 
-function containsPatterns(value: string): boolean {
-    return /\[\[([^\]]+)\]\]/.test(value);
 }
 
-function quadValueEquals(expected: string, actual: string): boolean {
-    if (!containsPatterns(expected))
-        return expected === actual;
+function assertExpectedQuadsExist(expectedQuads: Quad[], actualQuads: Quad[]): void {
+    for (const expectedQuad of expectedQuads) {
+        const matchingQuad = actualQuads.find(actualQuad => quadEquals(expectedQuad, actualQuad));
 
-    if (!(expected in patternRegExps)) {
-        const patternMatches = expected.matchAll(/\[\[([^\]]+)\]\]/g);
-        const patterns: string[] = [];
-        let expectedRegExp = expected;
+        if (!matchingQuad)
+            throw new ExpectedQuadAssertionError(expectedQuad);
 
-        for (const patternMatch of patternMatches) {
-            patterns.push(patternMatch[1]);
+        arrayRemove(actualQuads, matchingQuad);
+    }
+}
 
-            expectedRegExp = expectedRegExp.replace(patternMatch[0], `%PATTERN${patterns.length - 1}%`);
-        }
+function containsPatterns(value: string): boolean {
+    return /\[\[(.*\]\[)?([^\]]+)\]\]/.test(value);
+}
 
-        expectedRegExp = expectedRegExp.replace(/[-[\]{}()*+?.,\\^$|#\s]/g, '\\$&');
+function createPatternRegexp(expected: string): RegExp {
+    const patternAliases = [];
+    const patternMatches = stringMatchAll<4, 1 | 2>(
+        expected,
+        /\[\[((.*?)\]\[)?([^\]]+)\]\]/g,
+    );
+    const patterns: string[] = [];
+    let expectedRegExp = expected;
 
-        for (const [patternIndex, pattern] of Object.entries(patterns)) {
-            expectedRegExp = expectedRegExp.replace(`%PATTERN${patternIndex}%`, pattern);
-        }
+    for (const patternMatch of patternMatches) {
+        patternMatch[2] && patternAliases.push(patternMatch[2]);
+
+        patterns.push(patternMatch[3]);
 
-        patternRegExps[expected] = new RegExp(expectedRegExp);
+        expectedRegExp = expectedRegExp.replace(patternMatch[0], `%PATTERN${patterns.length - 1}%`);
     }
 
-    return patternRegExps[expected].test(actual);
+    expectedRegExp = expectedRegExp.replace(/[-[\]{}()*+?.,\\^$|#\s]/g, '\\$&');
+
+    for (const [patternIndex, pattern] of Object.entries(patterns)) {
+        expectedRegExp = expectedRegExp.replace(`%PATTERN${patternIndex}%`, builtInPatterns[pattern] ?? pattern);
+    }
+
+    return new RegExp(expectedRegExp);
+}
+
+function quadValueEquals(expected: string, actual: string): boolean {
+    return containsPatterns(expected)
+        ? (patternsRegExpsIndex[expected] ??= createPatternRegexp(expected)).test(actual)
+        : expected === actual;
 }
 
 function quadObjectEquals(expected: Quad_Object, actual: Quad_Object): boolean {
@@ -59,6 +87,10 @@ function quadEquals(expected: Quad, actual: Quad): boolean {
         && quadValueEquals(expected.predicate.value, actual.predicate.value);
 }
 
+function resetPatterns(): void {
+    patternsRegExpsIndex = {};
+}
+
 export interface EqualityResult {
     success: boolean;
     message: string;
@@ -66,8 +98,39 @@ export interface EqualityResult {
     actual: string;
 }
 
+export async function jsonldEquals(expected: JsonLD, actual: JsonLD): Promise<EqualityResult> {
+    // TODO catch parsing errors and improve message.
+    resetPatterns();
+
+    const expectedQuads = await jsonldToQuads(expected);
+    const actualQuads = await jsonldToQuads(actual);
+    const expectedTurtle = quadsToTurtle(expectedQuads);
+    const actualTurtle = quadsToTurtle(actualQuads);
+    const result = (success: boolean, message: string) => ({
+        success,
+        message,
+        expected: expectedTurtle,
+        actual: actualTurtle,
+    });
+
+    if (expectedQuads.length !== actualQuads.length)
+        return result(false, `Expected ${expectedQuads.length} triples, found ${actualQuads.length}.`);
+
+    try {
+        assertExpectedQuadsExist(expectedQuads, actualQuads);
+    } catch (error) {
+        if (!(error instanceof ExpectedQuadAssertionError))
+            throw error;
+
+        return result(false, error.message);
+    }
+
+    return result(true, 'jsonld matches');
+}
+
 export function sparqlEquals(expected: string, actual: string): EqualityResult {
     // TODO catch parsing errors and improve message.
+    resetPatterns();
 
     const expectedOperations = sparqlToQuadsSync(expected, { normalizeBlankNodes: true });
     const actualOperations = sparqlToQuadsSync(actual, { normalizeBlankNodes: true });
@@ -83,9 +146,16 @@ export function sparqlEquals(expected: string, actual: string): EqualityResult {
         if (expectedQuads.length !== actualQuads.length)
             return result(false, `Expected ${expectedQuads.length} ${operation} triples, found ${actualQuads.length}.`);
 
-        for (const expectedQuad of expectedQuads) {
-            if (!actualQuads.some(actualQuad => quadEquals(expectedQuad, actualQuad)))
-                return result(false, `Couldn't find the following ${operation} triple: ${quadToTurtle(expectedQuad)}`);
+        try {
+            assertExpectedQuadsExist(expectedQuads, actualQuads);
+        } catch (error) {
+            if (!(error instanceof ExpectedQuadAssertionError))
+                throw error;
+
+            return result(
+                false,
+                `Couldn't find the following ${operation} triple: ${quadToTurtle(error.expectedQuad)}`,
+            );
         }
     }
 
@@ -98,6 +168,7 @@ export function sparqlEquals(expected: string, actual: string): EqualityResult {
 
 export function turtleEquals(expected: string, actual: string): EqualityResult {
     // TODO catch parsing errors and improve message.
+    resetPatterns();
 
     const expectedQuads = turtleToQuadsSync(expected, { normalizeBlankNodes: true });
     const actualQuads = turtleToQuadsSync(actual, { normalizeBlankNodes: true });
@@ -106,9 +177,13 @@ export function turtleEquals(expected: string, actual: string): EqualityResult {
     if (expectedQuads.length !== actualQuads.length)
         return result(false, `Expected ${expectedQuads.length} triples, found ${actualQuads.length}.`);
 
-    for (const expectedQuad of expectedQuads) {
-        if (!actualQuads.some(actualQuad => quadEquals(expectedQuad, actualQuad)))
-            return result(false, `Couldn't find the following triple: ${quadToTurtle(expectedQuad)}`);
+    try {
+        assertExpectedQuadsExist(expectedQuads, actualQuads);
+    } catch (error) {
+        if (!(error instanceof ExpectedQuadAssertionError))
+            throw error;
+
+        return result(false, error.message);
     }
 
     return result(true, 'turtle matches');

package/src/helpers/vocabs.ts

@@ -6,6 +6,7 @@ export interface ExpandIRIOptions {
 }
 
 const knownPrefixes: RDFContext = {
+    acl: 'http://www.w3.org/ns/auth/acl#',
     foaf: 'http://xmlns.com/foaf/0.1/',
     pim: 'http://www.w3.org/ns/pim/space#',
     purl: 'http://purl.org/dc/terms/',
@@ -25,7 +26,7 @@ export function expandIRI(iri: string, options: Partial<ExpandIRIOptions> = {}):
 
     const [prefix, name] = iri.split(':');
 
-    if (name) {
+    if (prefix && name) {
         const expandedPrefix = knownPrefixes[prefix] ?? options.extraContext?.[prefix] ?? null;
 
         if (!expandedPrefix)

package/src/helpers/wac.ts

@@ -0,0 +1,45 @@
+import { objectWithoutEmpty, requireUrlParentDirectory, urlResolve } from '@noeldemartin/utils';
+
+import { fetchSolidDocumentIfFound } from '@/helpers/io';
+import type SolidDocument from '@/models/SolidDocument';
+import type { Fetch } from '@/helpers/io';
+
+async function fetchACLResourceUrl(resourceUrl: string, fetch: Fetch): Promise<string> {
+    fetch = fetch ?? window.fetch.bind(window);
+
+    const resourceHead = await fetch(resourceUrl, { method: 'HEAD' });
+    const linkHeader = resourceHead.headers.get('Link') ?? '';
+    const url = linkHeader.match(/<([^>]+)>;\s*rel="acl"/)?.[1] ?? null;
+
+    if (!url) {
+        throw new Error(`Could not find ACL Resource for '${resourceUrl}'`);
+    }
+
+    return urlResolve(requireUrlParentDirectory(resourceUrl), url);
+}
+
+async function fetchEffectiveACL(
+    resourceUrl: string,
+    fetch: Fetch,
+    aclResourceUrl?: string | null,
+): Promise<SolidDocument> {
+    aclResourceUrl = aclResourceUrl ?? await fetchACLResourceUrl(resourceUrl, fetch);
+
+    return await fetchSolidDocumentIfFound(aclResourceUrl ?? '', fetch)
+        ?? await fetchEffectiveACL(requireUrlParentDirectory(resourceUrl), fetch);
+}
+
+export async function fetchSolidDocumentACL(documentUrl: string, fetch: Fetch): Promise<{
+    url: string;
+    effectiveUrl: string;
+    document: SolidDocument;
+}> {
+    const url = await fetchACLResourceUrl(documentUrl, fetch);
+    const document = await fetchEffectiveACL(documentUrl, fetch, url);
+
+    return objectWithoutEmpty({
+        url,
+        effectiveUrl: document.url,
+        document,
+    });
+}

package/src/plugins/chai/assertions.ts

@@ -1,4 +1,4 @@
-import { sparqlEquals } from '@/helpers/testing';
+import { sparqlEquals, turtleEquals } from '@/helpers/testing';
 
 type CustomAssertions = {
     [assertion in keyof typeof assertions]: typeof assertions[assertion];
@@ -17,6 +17,15 @@ declare global {
 }
 
 const assertions: Record<string, (this: Chai.AssertionStatic, ...args: any[]) => void> = {
+    turtle(graph: string): void {
+        const self = this as unknown as Chai.AssertionStatic;
+        const actual = self._obj;
+        const assert = self.assert.bind(this);
+        const expected = graph;
+        const result = turtleEquals(expected, actual);
+
+        assert(result.success, result.message, '', result.expected, result.actual);
+    },
     sparql(query: string): void {
         const self = this as unknown as Chai.AssertionStatic;
         const actual = self._obj;
@@ -24,7 +33,7 @@ const assertions: Record<string, (this: Chai.AssertionStatic, ...args: any[]) =>
         const expected = query;
         const result = sparqlEquals(expected, actual);
 
-        assert(result.success, result.message, expected, actual);
+        assert(result.success, result.message, '', result.expected, result.actual);
     },
 };
 

package/src/plugins/cypress/types.d.ts

@@ -7,6 +7,7 @@ declare global {
         // TODO generate automatically
         interface Chainer<Subject> {
             (chainer: 'be.sparql', update: string): Cypress.Chainable<Subject>;
+            (chainer: 'be.turtle', graph: string): Cypress.Chainable<Subject>;
         }
 
     }

package/src/plugins/jest/matchers.ts

@@ -1,41 +1,54 @@
-import diff from 'jest-diff';
-
 import { normalizeSparql } from '@/helpers/io';
-import { sparqlEquals } from '@/helpers/testing';
+import { jsonldEquals, sparqlEquals } from '@/helpers/testing';
+import type { EqualityResult } from '@/helpers/testing';
+
+interface FormatResultOptions {
+    context: jest.MatcherContext;
+    hint: string;
+    expected: unknown;
+    received: unknown;
+}
+
+function formatResult(result: EqualityResult, options: FormatResultOptions) {
+    const pass = result.success;
+    const utils = options.context.utils;
+    const message = pass
+        ? () => [
+            result.message,
+            utils.matcherHint(options.hint),
+        ].join('\n\n')
+        : () => [
+            result.message,
+            utils.matcherHint(options.hint),
+            [
+                `Expected: not ${utils.printExpected(options.expected)}`,
+                `Received: ${utils.printReceived(options.received)}`,
+            ].join('\n'),
+        ].join('\n\n');
+
+    return { pass, message };
+}
 
 const matchers: jest.ExpectExtendMap = {
+    async toEqualJsonLD(received, expected) {
+        const result = await jsonldEquals(expected, received);
+
+        return formatResult(result, {
+            context: this,
+            hint: 'toEqualJsonLD',
+            expected,
+            received,
+        });
+    },
     toEqualSparql(received, expected) {
         const result = sparqlEquals(expected, received);
-        const pass = result.success;
-        const normalizedReceived = normalizeSparql(received);
-        const normalizedExpected = normalizeSparql(expected);
-        const message = pass
-            ? () => [
-                result.message,
-                this.utils.matcherHint('toEqualSparql'),
-                [
-                    `Expected: not ${this.utils.printExpected(normalizedExpected)}`,
-                    `Received: ${this.utils.printReceived(normalizedReceived)}`,
-                ].join('\n'),
-            ].join('\n\n')
-            : () => {
-                const diffString = diff(normalizedExpected, normalizedReceived, {
-                    expand: this.expand,
-                });
-
-                return [
-                    result.message,
-                    this.utils.matcherHint('toEqualJsonLD'),
-                    diffString && diffString.includes('- Expect')
-                        ? `Difference:\n\n${diffString}`
-                        : [
-                            `Expected: ${this.utils.printExpected(normalizedExpected)}`,
-                            `Received: ${this.utils.printReceived(normalizedReceived)}`,
-                        ].join('\n'),
-                ].join('\n\n');
-            };
 
-        return { pass, message };
+        return formatResult(result, {
+            context: this,
+            hint: 'toEqualSparql',
+            expected: normalizeSparql(expected),
+            received: normalizeSparql(received),
+        });
     },
 };
 

package/src/plugins/jest/types.d.ts

@@ -5,6 +5,7 @@ declare global {
         // TODO generate automatically
         interface Matchers<R> {
             toEqualSparql(sparql: string): R;
+            toEqualJsonLD(jsonld: JsonLD): Promise<R>;
         }
 
     }