@thomasfosterau/effect-rdf 0.0.0 → 0.1.0

package/src/ntriples/Lexical.ts

@@ -0,0 +1,321 @@
+/**
+ * Lexical rules shared by the N-Triples family of RDF syntaxes (N-Triples,
+ * N-Quads, Turtle and TriG): character classes, escape decoding, language
+ * tags with base direction, and canonical term formatting.
+ *
+ * These are low-level, pure helpers; most users want the `NTriples` and
+ * `NQuads` modules instead.
+ *
+ * @since 0.1.0
+ */
+import * as Term from '../Term.ts';
+import * as Match from 'effect/Match';
+
+const RDF = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#';
+const RDF_LANG_STRING = `${RDF}langString`;
+const RDF_DIR_LANG_STRING = `${RDF}dirLangString`;
+const XSD_STRING = 'http://www.w3.org/2001/XMLSchema#string';
+
+/**
+ * `PN_CHARS_BASE` from the Turtle / N-Triples grammars.
+ *
+ * @since 0.1.0
+ * @category character classes
+ */
+export const isPnCharsBase = (c: number): boolean =>
+  (c >= 0x41 && c <= 0x5a) ||
+  (c >= 0x61 && c <= 0x7a) ||
+  (c >= 0xc0 && c <= 0xd6) ||
+  (c >= 0xd8 && c <= 0xf6) ||
+  (c >= 0xf8 && c <= 0x2ff) ||
+  (c >= 0x370 && c <= 0x37d) ||
+  (c >= 0x37f && c <= 0x1fff) ||
+  (c >= 0x200c && c <= 0x200d) ||
+  (c >= 0x2070 && c <= 0x218f) ||
+  (c >= 0x2c00 && c <= 0x2fef) ||
+  (c >= 0x3001 && c <= 0xd7ff) ||
+  (c >= 0xf900 && c <= 0xfdcf) ||
+  (c >= 0xfdf0 && c <= 0xfffd) ||
+  (c >= 0x10000 && c <= 0xeffff);
+
+/**
+ * `PN_CHARS_U`: `PN_CHARS_BASE` or `_`.
+ *
+ * @since 0.1.0
+ * @category character classes
+ */
+export const isPnCharsU = (c: number): boolean => c === 0x5f || isPnCharsBase(c);
+
+/**
+ * `PN_CHARS`: `PN_CHARS_U`, `-`, digits, `·` and combining marks.
+ *
+ * @since 0.1.0
+ * @category character classes
+ */
+export const isPnChars = (c: number): boolean =>
+  isPnCharsU(c) ||
+  c === 0x2d ||
+  (c >= 0x30 && c <= 0x39) ||
+  c === 0xb7 ||
+  (c >= 0x300 && c <= 0x36f) ||
+  (c >= 0x203f && c <= 0x2040);
+
+/**
+ * Whether a code point is an ASCII digit.
+ *
+ * @since 0.1.0
+ * @category character classes
+ */
+export const isDigit = (c: number): boolean => c >= 0x30 && c <= 0x39;
+
+/**
+ * Whether a code point is an ASCII hexadecimal digit.
+ *
+ * @since 0.1.0
+ * @category character classes
+ */
+export const isHex = (c: number): boolean =>
+  (c >= 0x30 && c <= 0x39) || (c >= 0x41 && c <= 0x46) || (c >= 0x61 && c <= 0x66);
+
+/**
+ * Whether a code point may appear unescaped inside an `IRIREF`
+ * (`[^#x00-#x20<>"{}|^`\]`).
+ *
+ * @since 0.1.0
+ * @category character classes
+ */
+export const isIriChar = (c: number): boolean =>
+  c > 0x20 &&
+  c !== 0x3c && // <
+  c !== 0x3e && // >
+  c !== 0x22 && // "
+  c !== 0x7b && // {
+  c !== 0x7d && // }
+  c !== 0x7c && // |
+  c !== 0x5e && // ^
+  c !== 0x60 && // `
+  c !== 0x5c; // \
+
+// Hoisted: a regex literal makes a new `RegExp` each time it is evaluated, and this runs per IRI.
+const SCHEME = /^[A-Za-z][A-Za-z0-9+.-]*:/;
+
+/**
+ * Whether a string is an absolute IRI reference (starts with a scheme).
+ *
+ * @since 0.1.0
+ * @category validation
+ */
+export const isAbsoluteIri = (iri: string): boolean => SCHEME.test(iri);
+
+/**
+ * Whether an IRI can be written as an N-Triples / Turtle `IRIREF`: it is
+ * absolute and contains no characters that would need escaping.
+ *
+ * @since 0.1.0
+ * @category validation
+ */
+export const isWritableIri = (iri: string): boolean =>
+  // `escapeIri` changes exactly the characters `isIriChar` rejects
+  isAbsoluteIri(iri) && Term.escapeIri(iri) === iri;
+
+/** The code point of a one-code-point string (as `Array.from` splits a string). */
+const codePointOf = (ch: string): number => ch.codePointAt(0) ?? 0;
+
+const HEX_DIGITS = /^[0-9A-Fa-f]*$/;
+
+/**
+ * Whether a string is a valid `BLANK_NODE_LABEL` (without the `_:`).
+ *
+ * @since 0.1.0
+ * @category validation
+ */
+export const isBlankNodeLabel = (label: string): boolean => {
+  if (label === '') return false;
+  const codePoints = Array.from(label, codePointOf);
+  return (
+    codePoints.every((c, i) =>
+      i === 0 ? isPnCharsU(c) || isDigit(c) : isPnChars(c) || c === 0x2e,
+    ) && codePoints.at(-1) !== 0x2e
+  );
+};
+
+/**
+ * The result of decoding a numeric escape: the code point or an error
+ * message.
+ *
+ * @since 0.1.0
+ * @category escapes
+ */
+export type DecodedEscape =
+  | { readonly _tag: 'Ok'; readonly value: string; readonly length: number }
+  | { readonly _tag: 'Error'; readonly message: string };
+
+/**
+ * Decodes a `UCHAR` (`\uXXXX` or `\UXXXXXXXX`) starting at `index`, which
+ * must point at the backslash. Surrogate code points and values beyond
+ * U+10FFFF are rejected.
+ *
+ * @since 0.1.0
+ * @category escapes
+ */
+export const decodeUchar = (input: string, index: number): DecodedEscape => {
+  const kind = input.charCodeAt(index + 1);
+  const digits = kind === 0x75 ? 4 : kind === 0x55 ? 8 : 0;
+  if (digits === 0) return { _tag: 'Error', message: 'Invalid escape sequence' };
+  const hex = input.slice(index + 2, index + 2 + digits);
+  if (hex.length !== digits || !HEX_DIGITS.test(hex)) {
+    return { _tag: 'Error', message: 'Invalid numeric escape sequence' };
+  }
+  const value = parseInt(hex, 16);
+  if (value > 0x10ffff) {
+    return { _tag: 'Error', message: 'Numeric escape is beyond U+10FFFF' };
+  }
+  if (value >= 0xd800 && value <= 0xdfff) {
+    return { _tag: 'Error', message: 'Numeric escape encodes a surrogate code point' };
+  }
+  return { _tag: 'Ok', value: String.fromCodePoint(value), length: digits + 2 };
+};
+
+// Built once: `decodeEchar` runs for every backslash escape a lexer reads.
+const echar = Match.type<number>().pipe(
+  Match.when(0x74, () => '\t'),
+  Match.when(0x62, () => '\b'),
+  Match.when(0x6e, () => '\n'),
+  Match.when(0x72, () => '\r'),
+  Match.when(0x66, () => '\f'),
+  Match.when(0x22, () => '"'),
+  Match.when(0x27, () => "'"),
+  Match.when(0x5c, () => '\\'),
+  Match.orElse(() => undefined),
+);
+
+/**
+ * Decodes the string-escape (`ECHAR`) character following a backslash, if
+ * it is one of `t b n r f " ' \`.
+ *
+ * @since 0.1.0
+ * @category escapes
+ */
+export const decodeEchar = (c: number): string | undefined => echar(c);
+
+/**
+ * A language tag with an optional base direction.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface LanguageTag {
+  readonly language: string;
+  readonly direction: Term.Direction | undefined;
+}
+
+const LANG_DIR = /^([a-zA-Z]{1,8}(?:-[a-zA-Z0-9]{1,8})*)(?:--([a-zA-Z]+))?$/;
+
+/**
+ * Parses the text of a `LANG_DIR` token (without the leading `@`). Returns
+ * `undefined` when the tag or direction is invalid; directions must be
+ * `ltr` or `rtl`.
+ *
+ * @since 0.1.0
+ * @category validation
+ */
+export const parseLanguageTag = (text: string): LanguageTag | undefined => {
+  const m = LANG_DIR.exec(text);
+  if (m === null) return undefined;
+  const direction = m[2];
+  if (direction !== undefined && direction !== 'ltr' && direction !== 'rtl') return undefined;
+  return { language: m[1] ?? '', direction };
+};
+
+/**
+ * Builds a literal from a lexical form and an optional language tag or
+ * datatype, rejecting the language-string datatypes used without a tag.
+ * Returns an error message on failure.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const makeLiteral = (
+  value: string,
+  annotation: LanguageTag | Term.NamedNode | undefined,
+): Term.Literal | string => {
+  if (annotation === undefined) return Term.literal(value);
+  if (Term.isNamedNode(annotation)) {
+    if (annotation.value === RDF_LANG_STRING || annotation.value === RDF_DIR_LANG_STRING) {
+      return `The datatype ${annotation.key} requires a language tag`;
+    }
+    return new Term.Literal(value, annotation);
+  }
+  return Term.literal(value, annotation);
+};
+
+// -----------------------------------------------------------------------------
+// Canonical formatting
+// -----------------------------------------------------------------------------
+
+/**
+ * Encodes an arbitrary blank node label as a valid N-Triples label. Valid
+ * labels are returned unchanged.
+ *
+ * @since 0.1.0
+ * @category formatting
+ */
+export const blankNodeLabel = (label: string): string => {
+  if (isBlankNodeLabel(label)) return label;
+  return `x${Array.from(label, (ch) => {
+    const c = codePointOf(ch);
+    return isPnCharsBase(c) || isDigit(c) ? ch : `_${c.toString(16)}_`;
+  }).join('')}`;
+};
+
+/**
+ * Formats an IRI as a canonical `IRIREF`.
+ *
+ * @since 0.1.0
+ * @category formatting
+ */
+export const formatIri = (iri: string): string => `<${Term.escapeIri(iri)}>`;
+
+/**
+ * Formats a literal in canonical N-Triples form: canonical string escapes,
+ * lower-case language tags, and no datatype for `xsd:string`.
+ *
+ * @since 0.1.0
+ * @category formatting
+ */
+export const formatLiteral = (literal: Term.Literal): string => {
+  const lexical = `"${Term.escapeString(literal.value)}"`;
+  if (literal.language !== '') {
+    const language = literal.language.toLowerCase();
+    return literal.direction === undefined
+      ? `${lexical}@${language}`
+      : `${lexical}@${language}--${literal.direction}`;
+  }
+  if (literal.datatype.value === XSD_STRING) return lexical;
+  return `${lexical}^^${formatIri(literal.datatype.value)}`;
+};
+
+// Built once: `formatTerm` runs for every term a serializer writes.
+const formatTermMatch = Match.type<Term.Term>().pipe(
+  Match.tag('NamedNode', (term) => formatIri(term.value)),
+  Match.tag('BlankNode', (term) => `_:${blankNodeLabel(term.value)}`),
+  Match.tag('Literal', (term) => formatLiteral(term)),
+  Match.tag('Triple', (term) => {
+    const s = formatTerm(term.subject);
+    const o = formatTerm(term.object);
+    return s === undefined || o === undefined
+      ? undefined
+      : `<<( ${s} ${formatIri(term.predicate.value)} ${o} )>>`;
+  }),
+  Match.orElse(() => undefined),
+);
+
+/**
+ * Formats a ground term (IRI, blank node, literal or triple term) in
+ * canonical N-Triples form. Returns `undefined` for variables and the
+ * default graph, which have no N-Triples representation.
+ *
+ * @since 0.1.0
+ * @category formatting
+ */
+export const formatTerm = (term: Term.Term): string | undefined => formatTermMatch(term);

package/src/ntriples/NQuads.ts

@@ -0,0 +1,140 @@
+/**
+ * RDF 1.2 N-Quads: a line-based, plain-text format for RDF datasets.
+ *
+ * The parser is strict and streaming (see `NTriples`); the serializer emits
+ * canonical N-Quads.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from 'effect'
+ * import { NQuads } from '@thomasfosterau/effect-rdf/ntriples'
+ *
+ * const program = Effect.gen(function* () {
+ *   const { dataset } = yield* NQuads.parse('<http://ex/s> <http://ex/p> <http://ex/o> <http://ex/g> .\n')
+ *   return yield* NQuads.serialize(dataset, { sort: true })
+ * })
+ * ```
+ *
+ * @since 0.1.0
+ */
+import * as Serialization from '../Serialization.ts';
+import type * as Term from '../Term.ts';
+import type * as Effect from 'effect/Effect';
+import type * as Stream from 'effect/Stream';
+import * as internal from './internal/codec.ts';
+
+/**
+ * Options for the N-Quads serializer.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type SerializeOptions = internal.SerializeOptions;
+
+/**
+ * @since 0.1.0
+ * @category formats
+ */
+export const format: Serialization.Format = Serialization.makeFormat({
+  name: 'N-Quads',
+  mediaType: 'application/n-quads',
+  extensions: ['nq'],
+  datasets: true,
+});
+
+// The span names are `NQuads.parse`, `NQuads.serialize`, …
+const syntax: internal.Syntax = {
+  name: 'N-Quads',
+  quads: true,
+  trace: { module: 'NQuads', format },
+};
+
+/**
+ * Parses an N-Quads document. Statements without a graph label are placed
+ * in `options.graph` (the default graph when omitted).
+ *
+ * @since 0.1.0
+ * @category parsing
+ */
+export const parse = (
+  input: string,
+  options?: Serialization.ParseOptions,
+): Effect.Effect<Serialization.ParseResult, Serialization.RdfParseError> =>
+  internal.parse(syntax, input, options);
+
+/**
+ * Parses an N-Quads document into quads in document order (duplicates are
+ * kept).
+ *
+ * @since 0.1.0
+ * @category parsing
+ */
+export const parseQuads = (
+  input: string,
+  options?: Serialization.ParseOptions,
+): Effect.Effect<ReadonlyArray<Term.Quad>, Serialization.RdfParseError> =>
+  internal.parseQuads(syntax, input, options);
+
+/**
+ * Parses a stream of text chunks incrementally, line by line. Chunk
+ * boundaries may fall anywhere.
+ *
+ * @since 0.1.0
+ * @category parsing
+ */
+export const parseStream: <E, R>(
+  input: Stream.Stream<string, E, R>,
+  options?: Serialization.ParseOptions,
+) => Stream.Stream<Term.Quad, Serialization.RdfParseError | E, R> = internal.parseStream(syntax);
+
+/**
+ * Serialises quads as canonical N-Quads. Fails for triple terms in the
+ * subject position.
+ *
+ * @since 0.1.0
+ * @category serializing
+ */
+export const serialize = (
+  quads: Iterable<Term.Quad>,
+  options?: SerializeOptions,
+): Effect.Effect<string, Serialization.RdfSerializeError> =>
+  internal.serialize(syntax, quads, options);
+
+/**
+ * Serialises a stream of quads incrementally as canonical N-Quads.
+ *
+ * @since 0.1.0
+ * @category serializing
+ */
+export const serializeStream: <E, R>(
+  quads: Stream.Stream<Term.Quad, E, R>,
+  options?: SerializeOptions,
+) => Stream.Stream<string, Serialization.RdfSerializeError | E, R> =
+  internal.serializeStream(syntax);
+
+/**
+ * @since 0.1.0
+ * @category parsing
+ */
+export const parser: Serialization.Parser = Serialization.makeParser({
+  format,
+  parse,
+  parseStream,
+});
+
+/**
+ * @since 0.1.0
+ * @category serializing
+ */
+export const serializer: Serialization.Serializer<SerializeOptions> = Serialization.makeSerializer({
+  format,
+  serialize,
+  serializeStream,
+});
+
+/**
+ * @since 0.1.0
+ * @category codecs
+ */
+export const codec: Serialization.Codec<Serialization.ParseOptions, SerializeOptions> =
+  Serialization.makeCodec(parser, serializer);

package/src/ntriples/NTriples.ts

@@ -0,0 +1,143 @@
+/**
+ * RDF 1.2 N-Triples: a line-based, plain-text format for RDF graphs.
+ *
+ * The parser is strict (absolute IRIs only, validated escapes, language tags
+ * and base directions, triple terms `<<( s p o )>>` in object position,
+ * `VERSION` directives) and streaming: `parseStream` consumes text chunks
+ * line by line, so arbitrarily large documents are never buffered. The
+ * serializer emits canonical N-Triples.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from 'effect'
+ * import { NTriples } from '@thomasfosterau/effect-rdf/ntriples'
+ *
+ * const program = Effect.gen(function* () {
+ *   const { dataset } = yield* NTriples.parse('<http://ex/s> <http://ex/p> "o"@en .\n')
+ *   return yield* NTriples.serialize(dataset)
+ * })
+ * ```
+ *
+ * @since 0.1.0
+ */
+import * as Serialization from '../Serialization.ts';
+import type * as Term from '../Term.ts';
+import type * as Effect from 'effect/Effect';
+import type * as Stream from 'effect/Stream';
+import * as internal from './internal/codec.ts';
+
+/**
+ * Options for the N-Triples serializer.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export type SerializeOptions = internal.SerializeOptions;
+
+/**
+ * @since 0.1.0
+ * @category formats
+ */
+export const format: Serialization.Format = Serialization.makeFormat({
+  name: 'N-Triples',
+  mediaType: 'application/n-triples',
+  extensions: ['nt'],
+  datasets: false,
+});
+
+// The span names are `NTriples.parse`, `NTriples.serialize`, …
+const syntax: internal.Syntax = {
+  name: 'N-Triples',
+  quads: false,
+  trace: { module: 'NTriples', format },
+};
+
+/**
+ * Parses an N-Triples document. Triples are placed in `options.graph`
+ * (the default graph when omitted).
+ *
+ * @since 0.1.0
+ * @category parsing
+ */
+export const parse = (
+  input: string,
+  options?: Serialization.ParseOptions,
+): Effect.Effect<Serialization.ParseResult, Serialization.RdfParseError> =>
+  internal.parse(syntax, input, options);
+
+/**
+ * Parses an N-Triples document into quads in document order (duplicates are
+ * kept).
+ *
+ * @since 0.1.0
+ * @category parsing
+ */
+export const parseQuads = (
+  input: string,
+  options?: Serialization.ParseOptions,
+): Effect.Effect<ReadonlyArray<Term.Quad>, Serialization.RdfParseError> =>
+  internal.parseQuads(syntax, input, options);
+
+/**
+ * Parses a stream of text chunks incrementally, line by line. Chunk
+ * boundaries may fall anywhere.
+ *
+ * @since 0.1.0
+ * @category parsing
+ */
+export const parseStream: <E, R>(
+  input: Stream.Stream<string, E, R>,
+  options?: Serialization.ParseOptions,
+) => Stream.Stream<Term.Quad, Serialization.RdfParseError | E, R> = internal.parseStream(syntax);
+
+/**
+ * Serialises triples as canonical N-Triples. Fails for quads in named
+ * graphs and for triple terms in the subject position.
+ *
+ * @since 0.1.0
+ * @category serializing
+ */
+export const serialize = (
+  quads: Iterable<Term.Quad>,
+  options?: SerializeOptions,
+): Effect.Effect<string, Serialization.RdfSerializeError> =>
+  internal.serialize(syntax, quads, options);
+
+/**
+ * Serialises a stream of quads incrementally as canonical N-Triples.
+ *
+ * @since 0.1.0
+ * @category serializing
+ */
+export const serializeStream: <E, R>(
+  quads: Stream.Stream<Term.Quad, E, R>,
+  options?: SerializeOptions,
+) => Stream.Stream<string, Serialization.RdfSerializeError | E, R> =
+  internal.serializeStream(syntax);
+
+/**
+ * @since 0.1.0
+ * @category parsing
+ */
+export const parser: Serialization.Parser = Serialization.makeParser({
+  format,
+  parse,
+  parseStream,
+});
+
+/**
+ * @since 0.1.0
+ * @category serializing
+ */
+export const serializer: Serialization.Serializer<SerializeOptions> = Serialization.makeSerializer({
+  format,
+  serialize,
+  serializeStream,
+});
+
+/**
+ * @since 0.1.0
+ * @category codecs
+ */
+export const codec: Serialization.Codec<Serialization.ParseOptions, SerializeOptions> =
+  Serialization.makeCodec(parser, serializer);

package/src/ntriples/index.ts

@@ -0,0 +1,14 @@
+/**
+ * RDF 1.2 N-Triples and N-Quads for `@thomasfosterau/effect-rdf`.
+ *
+ * @since 0.1.0
+ */
+
+/** @since 0.1.0 */
+export * as Grammar from './Grammar.ts';
+/** @since 0.1.0 */
+export * as Lexical from './Lexical.ts';
+/** @since 0.1.0 */
+export * as NQuads from './NQuads.ts';
+/** @since 0.1.0 */
+export * as NTriples from './NTriples.ts';