@thomasfosterau/effect-rdf 0.0.0 → 0.1.0

package/src/internal/arbitrary.ts

@@ -0,0 +1,148 @@
+/**
+ * Generation representations for the term declarations' `toCodecArbitrary`
+ * hooks: `TermJson`-shaped schemas whose native arbitraries produce realistic
+ * values — IRIs from a small pool (so values collide across quads), BCP 47
+ * language tags, both base directions, well-formed lexical forms for common
+ * XSD datatypes, and triple terms nested at most two deep. Generated data is
+ * RDF 1.2: triple terms appear only in the object position (of a quad or of
+ * another triple term), never as subjects, as RDF 1.2 Concepts requires.
+ *
+ * Plain data only (no `Term` import), so `Term` can link to it without a
+ * cycle; `Term` decodes these with `fromJson` and checks the result.
+ */
+import * as Schema from 'effect/Schema';
+import type * as TermJson from '../TermJson.ts';
+
+const XSD = 'http://www.w3.org/2001/XMLSchema#';
+
+const NAMESPACES = [
+  'http://example.org/',
+  'http://example.org/vocab#',
+  'https://example.com/a/b/',
+  'urn:example:',
+];
+const LOCAL_NAMES = ['a', 'b', 'c', 'knows', 'name', 'Thing', 'x-1', 'é'];
+
+/** The IRI pool: every namespace × local name. */
+const IRIS = NAMESPACES.flatMap((ns) => LOCAL_NAMES.map((local) => `${ns}${local}`));
+
+const pattern = (re: RegExp): Schema.String => Schema.String.check(Schema.isPattern(re));
+
+const NamedNode: Schema.Codec<TermJson.NamedNode> = Schema.Struct({
+  type: Schema.Literal('uri'),
+  value: Schema.Literals(IRIS),
+});
+
+const BlankNode: Schema.Codec<TermJson.BlankNode> = Schema.Struct({
+  type: Schema.Literal('bnode'),
+  value: Schema.Literals(['b0', 'b1', 'b2', 'b3', 'node']),
+});
+
+const LANGUAGES = Schema.Literals([
+  'en',
+  'en-gb',
+  'fr',
+  'de-ch-1901',
+  'ar',
+  'zh-hant-tw',
+  'x-private',
+]);
+
+const typedLiteral = (local: string, value: Schema.Codec<string>) =>
+  Schema.Struct({
+    type: Schema.Literal('literal'),
+    value,
+    datatype: Schema.Literal(`${XSD}${local}`),
+  });
+
+const DATE = '(19|20)[0-9]{2}-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-8])';
+
+const Literal: Schema.Codec<TermJson.Literal> = Schema.Union([
+  Schema.Struct({
+    type: Schema.Literal('literal'),
+    value: Schema.String.check(Schema.isMaxLength(8)),
+  }),
+  Schema.Struct({
+    type: Schema.Literal('literal'),
+    value: Schema.Literals(['', 'a', 'Alice', 'hello world', 'ünïcödé']),
+    'xml:lang': LANGUAGES,
+  }),
+  Schema.Struct({
+    type: Schema.Literal('literal'),
+    value: Schema.Literals(['a', 'שלום', 'مرحبا']),
+    'xml:lang': LANGUAGES,
+    'its:dir': Schema.Literals(['ltr', 'rtl']),
+  }),
+  typedLiteral('integer', pattern(/^-?(0|[1-9][0-9]{0,5})$/)),
+  typedLiteral('decimal', pattern(/^-?(0|[1-9][0-9]{0,3})\.[0-9]{1,3}$/)),
+  typedLiteral('double', pattern(/^-?[1-9]\.[0-9]{1,3}E-?[0-9]$/)),
+  typedLiteral('boolean', Schema.Literals(['true', 'false'])),
+  typedLiteral('date', pattern(new RegExp(`^${DATE}$`))),
+  typedLiteral(
+    'dateTime',
+    pattern(new RegExp(`^${DATE}T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](Z|[+-]0[0-9]:00)?$`)),
+  ),
+]);
+
+const Resource = Schema.Union([NamedNode, BlankNode]);
+
+const tripleOf = (object: Schema.Codec<TermJson.GroundTerm>): Schema.Codec<TermJson.Triple> =>
+  Schema.Struct({
+    type: Schema.Literal('triple'),
+    value: Schema.Struct({ subject: Resource, predicate: NamedNode, object }),
+  });
+
+// Depth one: no triple term inside; depth two: a triple term as the object.
+const Triple1 = tripleOf(Schema.Union([NamedNode, BlankNode, Literal]));
+
+const Triple: Schema.Codec<TermJson.Triple> = tripleOf(
+  Schema.Union([NamedNode, BlankNode, Literal, Triple1]),
+);
+
+const Variable: Schema.Codec<TermJson.Variable> = Schema.Struct({
+  type: Schema.Literal('variable'),
+  value: Schema.Literals(['s', 'p', 'o', 'x']),
+});
+
+const DefaultGraph: Schema.Codec<TermJson.DefaultGraph> = Schema.Struct({
+  type: Schema.Literal('default-graph'),
+});
+
+const GroundTerm: Schema.Codec<TermJson.GroundTerm> = Schema.Union([
+  NamedNode,
+  BlankNode,
+  Literal,
+  Triple,
+]);
+
+const Term: Schema.Codec<TermJson.Term> = Schema.Union([
+  NamedNode,
+  BlankNode,
+  Literal,
+  Triple,
+  Variable,
+  DefaultGraph,
+]);
+
+const Quad: Schema.Codec<TermJson.Quad> = Schema.Struct({
+  subject: Resource,
+  predicate: NamedNode,
+  object: GroundTerm,
+  graph: Schema.optionalKey(Resource),
+});
+
+/** The representation each term declaration's `toCodecArbitrary` links to. */
+export const representations = {
+  NamedNode,
+  BlankNode,
+  Literal,
+  Triple,
+  Variable,
+  DefaultGraph,
+  GroundTerm,
+  Term,
+  Quad,
+} as const;
+
+/** The most quads a generated dataset holds. */
+export const MAX_DATASET_SIZE = 12;

package/src/internal/loop.ts

@@ -0,0 +1,24 @@
+/**
+ * A loop as a function, for the scans and searches that step a cursor until
+ * a condition holds (hashing a string, probing a hash table, walking a list,
+ * a depth-first search).
+ *
+ * @internal
+ */
+import * as Iterable from 'effect/Iterable';
+
+const BLOCK = 1024;
+
+/** `0 … BLOCK - 1`: the steps of one block run as an array scan, which engines optimise well. */
+const offsets: ReadonlyArray<number> = Array.from({ length: BLOCK }, (_, i) => i);
+
+/** The first step of each block after the first: `BLOCK, 2 * BLOCK, …`. */
+const blocks: Iterable<number> = Iterable.makeBy((b) => (b + 1) * BLOCK);
+
+/** Calls `step` with 0, 1, 2, … until it returns `false`. */
+export const loop = (step: (i: number) => boolean): void => {
+  // Most loops end within the first block, which needs no iterator
+  if (offsets.every((i) => step(i))) {
+    Iterable.some(blocks, (base) => offsets.some((i) => !step(base + i)));
+  }
+};

package/src/internal/pending.ts

@@ -0,0 +1,20 @@
+/**
+ * The quads of the datasets whose quad set has not been built yet
+ * (`Dataset.fromIterable` builds it on first use), shared by `Dataset` and
+ * the tracing in `Serialization`, which counts them without building it.
+ *
+ * @internal
+ */
+import type * as Term from '../Term.ts';
+
+/** @internal */
+export const pendingQuads: WeakMap<object, ReadonlyArray<Term.Quad>> = new WeakMap();
+
+/**
+ * How many statements a dataset was made from: its size, or for one not yet
+ * built, the number of quads given (counting any duplicates).
+ *
+ * @internal
+ */
+export const statementCount = (dataset: { readonly size: number }): number =>
+  pendingQuads.get(dataset)?.length ?? dataset.size;

package/src/internal/textDecoder.ts

@@ -0,0 +1,183 @@
+/**
+ * Incremental, strict text decoding for the byte entry points of
+ * `Serialization`. Validation is `TextDecoder`'s `fatal` mode; when it
+ * rejects UTF-8, a binary search over prefixes finds the exact bad byte, so
+ * the failure carries the line and column reached before it. A leading byte
+ * order mark is dropped. Other charsets go through a fatal `TextDecoder` too,
+ * with failures positioned at the start of the failing chunk.
+ */
+import * as Option from 'effect/Option';
+import * as Predicate from 'effect/Predicate';
+import * as Result from 'effect/Result';
+
+/** Where decoding failed: a message, and the 1-based line and column of the bad input. */
+export interface DecodeFailure {
+  readonly message: string;
+  readonly line: number;
+  readonly column: number;
+}
+
+/** A stateful decoder: `push` each chunk in order, then `end`. */
+export interface Decoder {
+  /** Decodes a chunk; a sequence split across chunks is completed by the next one. */
+  readonly push: (chunk: Uint8Array) => string | DecodeFailure;
+  /** Flushes the decoder; fails if the input ended inside a sequence. */
+  readonly end: () => string | DecodeFailure;
+}
+
+const isUtf8 = (charset: string): boolean => /^utf-?8$/i.test(charset.trim());
+
+/** The byte at `i` from the end of `bytes` (1 is the last), if there is one. */
+const fromEnd = (bytes: Uint8Array, i: number): Option.Option<number> =>
+  Option.fromUndefinedOr(bytes[bytes.length - i]);
+
+const isContinuation = (b: Option.Option<number>): boolean =>
+  Option.exists(b, (byte) => byte >= 0x80 && byte < 0xc0);
+
+// The length of the sequence a lead byte starts (1 for anything that is not a multi-byte lead).
+const sequenceLength = (lead: Option.Option<number>): number =>
+  Option.match(lead, {
+    onNone: () => 1,
+    onSome: (l) => (l < 0xc2 ? 1 : l < 0xe0 ? 2 : l < 0xf0 ? 3 : l < 0xf5 ? 4 : 1),
+  });
+
+/**
+ * How many trailing bytes start a sequence the chunk does not finish (0–3):
+ * they are held back for the next chunk. Whether they are well formed is
+ * left to the decoder.
+ */
+const incompleteTail = (bytes: Uint8Array): number => {
+  if (sequenceLength(fromEnd(bytes, 1)) > 1) return 1;
+  if (sequenceLength(fromEnd(bytes, 2)) > 2 && isContinuation(fromEnd(bytes, 1))) return 2;
+  if (
+    sequenceLength(fromEnd(bytes, 3)) > 3 &&
+    isContinuation(fromEnd(bytes, 2)) &&
+    isContinuation(fromEnd(bytes, 1))
+  )
+    return 3;
+  return 0;
+};
+
+const fatalUtf8 = (bytes: Uint8Array, stream: boolean): Result.Result<string, unknown> =>
+  Result.try(() =>
+    new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes, { stream }),
+  );
+
+/**
+ * The length of the longest prefix of `bytes` with no ill-formed byte (an
+ * incomplete sequence at its end is allowed), given that `bytes.subarray(0,
+ * valid)` has none and `bytes.subarray(0, invalid)` has one.
+ */
+const validPrefix = (bytes: Uint8Array, valid: number, invalid: number): number => {
+  if (invalid - valid <= 1) return valid;
+  const mid = Math.floor((valid + invalid) / 2);
+  return Result.isSuccess(fatalUtf8(bytes.subarray(0, mid), true))
+    ? validPrefix(bytes, mid, invalid)
+    : validPrefix(bytes, valid, mid);
+};
+
+class Position {
+  line = 1;
+  column = 1;
+  advance(text: string): void {
+    const lines = text.split('\n');
+    const last = lines.at(-1) ?? '';
+    if (lines.length === 1) this.column += last.length;
+    else {
+      this.line += lines.length - 1;
+      this.column = last.length + 1;
+    }
+  }
+  fail(message: string): DecodeFailure {
+    return { message, line: this.line, column: this.column };
+  }
+}
+
+const concat = (a: Uint8Array, b: Uint8Array): Uint8Array => {
+  if (a.byteLength === 0) return b;
+  const out = new Uint8Array(a.byteLength + b.byteLength);
+  out.set(a);
+  out.set(b, a.byteLength);
+  return out;
+};
+
+const utf8Decoder = (): Decoder => {
+  const position = new Position();
+  let carry: Uint8Array = new Uint8Array(0);
+  let atStart = true;
+  // Drop a byte order mark at the very start of the input.
+  const withoutBom = (text: string): string =>
+    atStart && text.startsWith('') ? text.slice(1) : text;
+  const decode = (bytes: Uint8Array): string | DecodeFailure =>
+    Result.match(fatalUtf8(bytes, false), {
+      onSuccess: (text) => {
+        const out = withoutBom(text);
+        if (text !== '') atStart = false;
+        position.advance(out);
+        return out;
+      },
+      onFailure: () => {
+        // Either the bytes end inside a sequence (a streaming decode accepts them) or one is bad.
+        const bad = Result.isSuccess(fatalUtf8(bytes, true))
+          ? bytes.length
+          : validPrefix(bytes, 0, bytes.length);
+        // The text before the bad byte: the valid prefix, without a sequence it leaves unfinished.
+        position.advance(
+          withoutBom(Result.getOrElse(fatalUtf8(bytes.subarray(0, bad), true), () => '')),
+        );
+        const byte = bytes[bad];
+        return position.fail(
+          byte === undefined
+            ? 'Invalid UTF-8: the input ends inside a multi-byte sequence'
+            : `Invalid UTF-8: byte 0x${byte.toString(16).padStart(2, '0')} cannot appear here`,
+        );
+      },
+    });
+  return {
+    push: (chunk) => {
+      const bytes = concat(carry, chunk);
+      const complete = bytes.byteLength - incompleteTail(bytes);
+      carry = bytes.slice(complete);
+      return decode(bytes.subarray(0, complete));
+    },
+    end: () => (carry.byteLength === 0 ? '' : decode(carry)),
+  };
+};
+
+const otherDecoder = (charset: string): Decoder => {
+  const position = new Position();
+  let text: Option.Option<TextDecoder> = Option.none();
+  const run = (chunk: Option.Option<Uint8Array>): string | DecodeFailure =>
+    Result.match(
+      Result.try({
+        try: () => {
+          const decoder = Option.getOrElse(text, () => new TextDecoder(charset, { fatal: true }));
+          text = Option.some(decoder);
+          return Option.match(chunk, {
+            onNone: () => decoder.decode(),
+            onSome: (bytes) => decoder.decode(bytes, { stream: true }),
+          });
+        },
+        catch: (error) =>
+          error instanceof RangeError
+            ? `Unsupported charset: ${charset}`
+            : `Invalid ${charset}: the input is not well formed`,
+      }),
+      {
+        onSuccess: (decoded) => {
+          position.advance(decoded);
+          return decoded;
+        },
+        onFailure: (message) => position.fail(message),
+      },
+    );
+  return { push: (chunk) => run(Option.some(chunk)), end: () => run(Option.none()) };
+};
+
+/** A decoder for `charset` (default UTF-8). */
+export const make = (charset: string = 'utf-8'): Decoder =>
+  isUtf8(charset) ? utf8Decoder() : otherDecoder(charset);
+
+/** Whether `push` / `end` failed. */
+export const isFailure = (result: string | DecodeFailure): result is DecodeFailure =>
+  !Predicate.isString(result);