@thomasfosterau/effect-rdf 0.0.0 → 0.1.0

package/src/csvw/internal/object.ts

@@ -0,0 +1,23 @@
+/**
+ * Building objects whose optional properties are set only when present, as
+ * `exactOptionalPropertyTypes` requires.
+ *
+ * @internal
+ */
+import * as Option from 'effect/Option';
+import * as Record from 'effect/Record';
+
+/**
+ * `{ [key]: value }` when the value is present, `{}` otherwise; spread it
+ * into an object literal.
+ *
+ * @internal
+ */
+export const optional = <K extends string, A>(
+  key: K,
+  value: Option.Option<A>,
+): { readonly [P in K]?: A } =>
+  Option.match(value, {
+    onNone: (): { readonly [P in K]?: A } => ({}),
+    onSome: (v): { readonly [P in K]?: A } => Record.singleton(key, v),
+  });

package/src/csvw/internal/uriTemplate.ts

@@ -0,0 +1,130 @@
+/**
+ * RFC 6570 URI Template expansion (all four levels) over string and list
+ * values, for the `aboutUrl`, `propertyUrl` and `valueUrl` templates.
+ *
+ * @internal
+ */
+import * as Arr from 'effect/Array';
+import * as Option from 'effect/Option';
+import * as Predicate from 'effect/Predicate';
+import * as Record from 'effect/Record';
+
+/**
+ * A template variable's value: a string, a list of strings, or absent.
+ *
+ * @internal
+ */
+export type Value = string | ReadonlyArray<string>;
+
+interface Operator {
+  readonly first: string;
+  readonly sep: string;
+  readonly named: boolean;
+  readonly ifEmpty: string;
+  readonly reserved: boolean;
+}
+
+const operators: Readonly<Record<string, Operator>> = {
+  '': { first: '', sep: ',', named: false, ifEmpty: '', reserved: false },
+  '+': { first: '', sep: ',', named: false, ifEmpty: '', reserved: true },
+  '.': { first: '.', sep: '.', named: false, ifEmpty: '', reserved: false },
+  '/': { first: '/', sep: '/', named: false, ifEmpty: '', reserved: false },
+  ';': { first: ';', sep: ';', named: true, ifEmpty: '', reserved: false },
+  '?': { first: '?', sep: '&', named: true, ifEmpty: '=', reserved: false },
+  '&': { first: '&', sep: '&', named: true, ifEmpty: '=', reserved: false },
+  '#': { first: '#', sep: ',', named: false, ifEmpty: '', reserved: true },
+};
+
+const utf8 = new TextEncoder();
+
+const pct = (c: string): string =>
+  Arr.join(
+    Arr.map(Array.from(utf8.encode(c)), (b) => `%${b.toString(16).toUpperCase().padStart(2, '0')}`),
+    '',
+  );
+
+const encodeUnreserved = (s: string): string => s.replace(/[^A-Za-z0-9\-._~]/gu, (c) => pct(c));
+
+const encodeReserved = (s: string): string =>
+  s.replace(/%[0-9A-Fa-f]{2}|[^A-Za-z0-9\-._~:/?#[\]@!$&'()*+,;=]/gu, (c) =>
+    c.startsWith('%') && c.length === 3 ? c : pct(c),
+  );
+
+interface VarSpec {
+  readonly name: string;
+  readonly prefix: Option.Option<number>;
+  readonly explode: boolean;
+}
+
+const parseVarSpec = (spec: string): VarSpec => {
+  const explode = spec.endsWith('*');
+  const body = explode ? spec.slice(0, -1) : spec;
+  const colon = body.indexOf(':');
+  return colon === -1
+    ? { name: body, prefix: Option.none(), explode }
+    : {
+        name: body.slice(0, colon),
+        prefix: Option.some(Number.parseInt(body.slice(colon + 1), 10)),
+        explode,
+      };
+};
+
+const expandVar = (
+  op: Operator,
+  spec: VarSpec,
+  defined: Option.Option<Value>,
+): ReadonlyArray<string> => {
+  const enc = op.reserved ? encodeReserved : encodeUnreserved;
+  if (Option.isNone(defined)) return [];
+  const value = defined.value;
+  if (Predicate.isString(value)) {
+    const v = Option.match(spec.prefix, {
+      onNone: () => value,
+      onSome: (n) => Arr.join(Arr.take(Array.from(value), n), ''),
+    });
+    if (!op.named) return [enc(v)];
+    return [v === '' ? `${spec.name}${op.ifEmpty}` : `${spec.name}=${enc(v)}`];
+  }
+  if (!Arr.isReadonlyArrayNonEmpty(value)) return [];
+  if (!spec.explode) {
+    const joined = Arr.join(Arr.map(value, enc), ',');
+    return [op.named ? `${spec.name}=${joined}` : joined];
+  }
+  return Arr.map(value, (item) =>
+    op.named
+      ? item === ''
+        ? `${spec.name}${op.ifEmpty}`
+        : `${spec.name}=${enc(item)}`
+      : enc(item),
+  );
+};
+
+const expandExpression = (
+  expression: string,
+  variables: Readonly<Record<string, Value>>,
+): string => {
+  const head = expression.charAt(0);
+  const op = Record.get(operators, head);
+  const [operator, body] = Option.match(op, {
+    onNone: () => [operators[''], expression] as const,
+    onSome: (o) => [o, expression.slice(1)] as const,
+  });
+  const resolved = operator ?? { first: '', sep: ',', named: false, ifEmpty: '', reserved: false };
+  const parts = Arr.flatMap(body.split(','), (raw) => {
+    const spec = parseVarSpec(raw);
+    return expandVar(resolved, spec, Record.get(variables, spec.name));
+  });
+  return Arr.match(parts, {
+    onEmpty: () => '',
+    onNonEmpty: (ps) => resolved.first + Arr.join(ps, resolved.sep),
+  });
+};
+
+/**
+ * Expands a URI template with the given variables (an absent variable is
+ * undefined).
+ *
+ * @internal
+ */
+export const expand = (template: string, variables: Readonly<Record<string, Value>>): string =>
+  template.replace(/\{([^}]*)\}/g, (_, e: string) => expandExpression(e, variables));

package/src/csvw/internal/url.ts

@@ -0,0 +1,93 @@
+/**
+ * URL helpers: resolution, RFC 3986 syntax- and scheme-based normalization
+ * (Tabular Data Model §URL Normalization) and the percent-encoding of column
+ * names derived from titles.
+ *
+ * @internal
+ */
+import { Iri } from '../../index.ts';
+
+/**
+ * Resolves a reference against a base URL.
+ *
+ * @internal
+ */
+export const resolve = (reference: string, base: string): string => Iri.resolve(reference, base);
+
+const URL_RE = /^([A-Za-z][A-Za-z0-9+.-]*):(?:\/\/([^/?#]*))?([^?#]*)(\?[^#]*)?(#.*)?$/;
+const UNRESERVED = /[A-Za-z0-9\-._~]/;
+
+const normalizePercent = (s: string): string =>
+  s.replace(/%([0-9A-Fa-f]{2})/g, (_, hex: string) => {
+    const c = String.fromCharCode(Number.parseInt(hex, 16));
+    return UNRESERVED.test(c) ? c : `%${hex.toUpperCase()}`;
+  });
+
+const isDefaultPort = (scheme: string, port: string): boolean =>
+  (scheme === 'http' && port === '80') || (scheme === 'https' && port === '443');
+
+const normalizeAuthority = (authority: string, scheme: string): string => {
+  const at = authority.lastIndexOf('@');
+  const userinfo = at === -1 ? '' : authority.slice(0, at + 1);
+  const hostPort = (at === -1 ? authority : authority.slice(at + 1)).toLowerCase();
+  const m = /^(.*?)(?::(\d*))?$/.exec(hostPort);
+  const host = m?.[1] ?? hostPort;
+  const port = m?.[2];
+  const keep = port !== undefined && port !== '' && !isDefaultPort(scheme, port);
+  return `${userinfo}${host}${keep ? `:${port}` : ''}`;
+};
+
+/**
+ * Normalizes a URL for comparison: lower-case scheme and host, upper-case
+ * percent-encodings, decoded unreserved characters, no dot segments, no
+ * default HTTP(S) port and a `/` path for an HTTP(S) URL with an authority.
+ *
+ * @internal
+ */
+export const normalize = (url: string): string => {
+  const m = URL_RE.exec(url);
+  if (m === null) return url;
+  const scheme = (m[1] ?? '').toLowerCase();
+  const authority = m[2];
+  const rawPath = normalizePercent(m[3] ?? '');
+  const path = Iri.removeDotSegments(rawPath);
+  const query = m[4] === undefined ? '' : normalizePercent(m[4]);
+  const fragment = m[5] === undefined ? '' : normalizePercent(m[5]);
+  if (authority === undefined) return `${scheme}:${path}${query}${fragment}`;
+  const p = path === '' && (scheme === 'http' || scheme === 'https') ? '/' : path;
+  return `${scheme}://${normalizeAuthority(authority, scheme)}${p}${query}${fragment}`;
+};
+
+/**
+ * Percent-encodes every character of a title that cannot appear in a URI
+ * template variable name (anything but `A-Z`, `a-z`, `0-9`, `_` and `.`),
+ * for a column name derived from it.
+ *
+ * @internal
+ */
+export const encodeName = (title: string): string =>
+  encodeURIComponent(title).replace(
+    /[!'()*~-]/g,
+    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+
+/**
+ * Percent-decodes a column name (`_name` and JSON property names).
+ *
+ * @internal
+ */
+export const decodeName = (name: string): string =>
+  name.replace(/(?:%[0-9A-Fa-f]{2})+/g, (run) => {
+    const bytes = run.match(/%([0-9A-Fa-f]{2})/g) ?? [];
+    const decoded = new TextDecoder('utf-8', { fatal: false }).decode(
+      Uint8Array.from(bytes, (b) => Number.parseInt(b.slice(1), 16)),
+    );
+    return decoded;
+  });
+
+/**
+ * Removes the fragment from a URL.
+ *
+ * @internal
+ */
+export const withoutFragment = (url: string): string => Iri.withoutFragment(url);

package/src/csvw/internal/vocab.ts

@@ -0,0 +1,282 @@
+/**
+ * The fixed CSVW JSON-LD context (`http://www.w3.org/ns/csvw`): its prefixes
+ * (the RDFa 1.1 initial context plus `csvw`), its terms, prefixed-name
+ * expansion and URL compaction (Metadata Vocabulary §URL Compaction).
+ *
+ * @internal
+ */
+import * as Arr from 'effect/Array';
+import * as Option from 'effect/Option';
+import * as Order from 'effect/Order';
+import * as Record from 'effect/Record';
+
+/** @internal */
+export const CSVW = 'http://www.w3.org/ns/csvw#';
+/** @internal */
+export const XSD = 'http://www.w3.org/2001/XMLSchema#';
+/** @internal */
+export const RDF = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#';
+/** @internal */
+export const RDFS = 'http://www.w3.org/2000/01/rdf-schema#';
+
+/**
+ * The prefixes of the CSVW context, which metadata MUST NOT override.
+ *
+ * @internal
+ */
+export const prefixes: Readonly<Record<string, string>> = {
+  as: 'https://www.w3.org/ns/activitystreams#',
+  cc: 'http://creativecommons.org/ns#',
+  csvw: CSVW,
+  ctag: 'http://commontag.org/ns#',
+  dc: 'http://purl.org/dc/terms/',
+  dc11: 'http://purl.org/dc/elements/1.1/',
+  dcat: 'http://www.w3.org/ns/dcat#',
+  dcterms: 'http://purl.org/dc/terms/',
+  dctypes: 'http://purl.org/dc/dcmitype/',
+  dqv: 'http://www.w3.org/ns/dqv#',
+  duv: 'https://www.w3.org/TR/vocab-duv#',
+  foaf: 'http://xmlns.com/foaf/0.1/',
+  gr: 'http://purl.org/goodrelations/v1#',
+  grddl: 'http://www.w3.org/2003/g/data-view#',
+  ical: 'http://www.w3.org/2002/12/cal/icaltzd#',
+  ldp: 'http://www.w3.org/ns/ldp#',
+  ma: 'http://www.w3.org/ns/ma-ont#',
+  oa: 'http://www.w3.org/ns/oa#',
+  og: 'http://ogp.me/ns#',
+  org: 'http://www.w3.org/ns/org#',
+  owl: 'http://www.w3.org/2002/07/owl#',
+  prov: 'http://www.w3.org/ns/prov#',
+  qb: 'http://purl.org/linked-data/cube#',
+  rdf: RDF,
+  rdfa: 'http://www.w3.org/ns/rdfa#',
+  rdfs: RDFS,
+  rev: 'http://purl.org/stuff/rev#',
+  rif: 'http://www.w3.org/2007/rif#',
+  rr: 'http://www.w3.org/ns/r2rml#',
+  schema: 'http://schema.org/',
+  sd: 'http://www.w3.org/ns/sparql-service-description#',
+  sioc: 'http://rdfs.org/sioc/ns#',
+  skos: 'http://www.w3.org/2004/02/skos/core#',
+  skosxl: 'http://www.w3.org/2008/05/skos-xl#',
+  v: 'http://rdf.data-vocabulary.org/#',
+  vcard: 'http://www.w3.org/2006/vcard/ns#',
+  void: 'http://rdfs.org/ns/void#',
+  wdr: 'http://www.w3.org/2007/05/powder#',
+  wrds: 'http://www.w3.org/2007/05/powder-s#',
+  xhv: 'http://www.w3.org/1999/xhtml/vocab#',
+  xsd: XSD,
+};
+
+const xsdTerms = [
+  'anyURI',
+  'base64Binary',
+  'boolean',
+  'byte',
+  'date',
+  'dateTime',
+  'dayTimeDuration',
+  'dateTimeStamp',
+  'decimal',
+  'double',
+  'duration',
+  'float',
+  'gDay',
+  'gMonth',
+  'gMonthDay',
+  'gYear',
+  'gYearMonth',
+  'hexBinary',
+  'int',
+  'integer',
+  'language',
+  'long',
+  'Name',
+  'NCName',
+  'NMTOKEN',
+  'negativeInteger',
+  'nonNegativeInteger',
+  'nonPositiveInteger',
+  'normalizedString',
+  'positiveInteger',
+  'QName',
+  'short',
+  'string',
+  'time',
+  'token',
+  'unsignedByte',
+  'unsignedInt',
+  'unsignedLong',
+  'unsignedShort',
+  'yearMonthDuration',
+] as const;
+
+const csvwClasses = [
+  'Cell',
+  'Column',
+  'Datatype',
+  'Dialect',
+  'Direction',
+  'ForeignKey',
+  'NumericFormat',
+  'Row',
+  'Schema',
+  'Table',
+  'TableGroup',
+  'TableReference',
+  'Transformation',
+  'JSON',
+  'uriTemplate',
+] as const;
+
+const csvwProperties: Readonly<Record<string, string>> = {
+  aboutUrl: 'aboutUrl',
+  base: 'base',
+  columnReference: 'columnReference',
+  columns: 'column',
+  commentPrefix: 'commentPrefix',
+  datatype: 'datatype',
+  decimalChar: 'decimalChar',
+  default: 'default',
+  describes: 'describes',
+  delimiter: 'delimiter',
+  dialect: 'dialect',
+  doubleQuote: 'doubleQuote',
+  encoding: 'encoding',
+  foreignKeys: 'foreignKey',
+  format: 'format',
+  groupChar: 'groupChar',
+  header: 'header',
+  headerRowCount: 'headerRowCount',
+  lang: 'lang',
+  length: 'length',
+  lineTerminators: 'lineTerminators',
+  maxExclusive: 'maxExclusive',
+  maxInclusive: 'maxInclusive',
+  maxLength: 'maxLength',
+  minExclusive: 'minExclusive',
+  minInclusive: 'minInclusive',
+  minLength: 'minLength',
+  name: 'name',
+  notes: 'note',
+  null: 'null',
+  ordered: 'ordered',
+  pattern: 'pattern',
+  primaryKey: 'primaryKey',
+  propertyUrl: 'propertyUrl',
+  quoteChar: 'quoteChar',
+  reference: 'reference',
+  referencedRows: 'referencedRow',
+  required: 'required',
+  resource: 'resource',
+  row: 'row',
+  rowTitles: 'rowTitle',
+  rownum: 'rownum',
+  scriptFormat: 'scriptFormat',
+  schemaReference: 'schemaReference',
+  separator: 'separator',
+  skipBlankRows: 'skipBlankRows',
+  skipColumns: 'skipColumns',
+  skipInitialSpace: 'skipInitialSpace',
+  skipRows: 'skipRows',
+  source: 'source',
+  suppressOutput: 'suppressOutput',
+  tables: 'table',
+  tableDirection: 'tableDirection',
+  tableSchema: 'tableSchema',
+  targetFormat: 'targetFormat',
+  transformations: 'transformations',
+  textDirection: 'textDirection',
+  titles: 'title',
+  trim: 'trim',
+  url: 'url',
+  valueUrl: 'valueUrl',
+  virtual: 'virtual',
+};
+
+/**
+ * Every term of the CSVW context mapped to its absolute IRI.
+ *
+ * @internal
+ */
+export const terms: Readonly<Record<string, string>> = {
+  ...Record.map(prefixes, (iri) => iri),
+  xml: `${RDF}XMLLiteral`,
+  html: `${RDF}HTML`,
+  json: `${CSVW}JSON`,
+  any: `${XSD}anyAtomicType`,
+  anyAtomicType: `${XSD}anyAtomicType`,
+  binary: `${XSD}base64Binary`,
+  datetime: `${XSD}dateTime`,
+  number: `${XSD}double`,
+  describedby: 'http://www.w3.org/2007/05/powder-s#describedby',
+  license: 'http://www.w3.org/1999/xhtml/vocab#license',
+  role: 'http://www.w3.org/1999/xhtml/vocab#role',
+  maximum: `${CSVW}maxInclusive`,
+  minimum: `${CSVW}minInclusive`,
+  ...Record.fromEntries(Arr.map(xsdTerms, (t) => [t, `${XSD}${t}`] as const)),
+  ...Record.fromEntries(Arr.map(csvwClasses, (t) => [t, `${CSVW}${t}`] as const)),
+  ...Record.map(csvwProperties, (local) => `${CSVW}${local}`),
+};
+
+const PREFIXED = /^([A-Za-z][\w.-]*):(.*)$/;
+
+/**
+ * The expansion of `value` if it is a prefixed name with a CSVW prefix.
+ *
+ * @internal
+ */
+export const expandPrefixed = (value: string): Option.Option<string> =>
+  Option.flatMap(Option.fromNullishOr(PREFIXED.exec(value)), (m) =>
+    Option.map(Record.get(prefixes, m[1] ?? ''), (ns) => ns + (m[2] ?? '')),
+  );
+
+/**
+ * Expands a term or prefixed name of the CSVW context; anything else is
+ * returned unchanged.
+ *
+ * @internal
+ */
+export const expand = (value: string): string =>
+  Option.getOrElse(Record.get(terms, value), () =>
+    Option.getOrElse(expandPrefixed(value), () => value),
+  );
+
+/**
+ * Whether `value` is an absolute URL (has a scheme).
+ *
+ * @internal
+ */
+export const isAbsoluteUrl = (value: string): boolean => /^[A-Za-z][A-Za-z0-9+.-]*:/.test(value);
+
+// Longest namespace first; `dc` and `dcterms` share one, and `dc` wins.
+const compactable: ReadonlyArray<readonly [string, string]> = Arr.sort(
+  Arr.filter(Record.toEntries(prefixes), ([prefix]) => prefix !== 'dcterms'),
+  Order.mapInput(Order.Number, ([, ns]: readonly [string, string]) => -ns.length),
+);
+
+const termOf: Readonly<Record<string, string>> = Record.fromEntries(
+  Arr.map(
+    Arr.filter(Record.toEntries(terms), ([term]) => !Record.has(prefixes, term)),
+    ([term, iri]) => [iri, term] as const,
+  ),
+);
+
+/**
+ * URL compaction (Metadata Vocabulary §URL Compaction): an absolute URL to a
+ * term or prefixed name of the CSVW context; `rdf:type` becomes `@type`.
+ *
+ * @internal
+ */
+export const compact = (url: string): string =>
+  url === `${RDF}type`
+    ? '@type'
+    : Option.getOrElse(Record.get(termOf, url), () =>
+        Option.getOrElse(
+          Option.map(
+            Arr.findFirst(compactable, ([, ns]) => url.startsWith(ns) && url.length > ns.length),
+            ([prefix, ns]) => `${prefix}:${url.slice(ns.length)}`,
+          ),
+          () => url,
+        ),
+      );

package/src/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Effect-idiomatic RDF 1.2: terms, datasets, vocabularies, RDF Schema,
+ * RDF-star reification and the serialisation interfaces implemented by the
+ * syntax packages.
+ *
+ * @since 0.1.0
+ */
+
+/** @since 0.1.0 */
+export * as Dataset from './Dataset.ts';
+/** @since 0.1.0 */
+export * as Iri from './Iri.ts';
+/** @since 0.1.0 */
+export * as Isomorphism from './Isomorphism.ts';
+/** @since 0.1.0 */
+export * as LanguageTag from './LanguageTag.ts';
+/** @since 0.1.0 */
+export * as Namespace from './Namespace.ts';
+/** @since 0.1.0 */
+export * as PrefixMap from './PrefixMap.ts';
+/** @since 0.1.0 */
+export * as RdfJs from './RdfJs.ts';
+/** @since 0.1.0 */
+export * as Rdfs from './Rdfs.ts';
+/** @since 0.1.0 */
+export * as Reification from './Reification.ts';
+/** @since 0.1.0 */
+export * as Resource from './Resource.ts';
+/** @since 0.1.0 */
+export * as Serialization from './Serialization.ts';
+/** @since 0.1.0 */
+export * as Term from './Term.ts';
+/** @since 0.1.0 */
+export * as TermCodec from './TermCodec.ts';
+/** @since 0.1.0 */
+export * as TermJson from './TermJson.ts';
+/** @since 0.1.0 */
+export * as Vocab from './Vocab.ts';
+/** @since 0.1.0 */
+export * as Xsd from './Xsd.ts';