From 46acfbbd947fe100ee3d6642d0afdbffe50848b1 Mon Sep 17 00:00:00 2001
From: Ruben Taelman <rubensworks@users.noreply.github.com>
Date: Tue, 7 Jan 2025 12:50:48 +0100
Subject: [PATCH] Add optional direction for literals (#38)

* Add optional direction for literals

* Add changeset

* Also allow null directions
---
 .changeset/famous-parrots-rush.md |  5 +++++
 data-model.d.ts                   | 28 ++++++++++++++++++++--------
 rdf-js-tests.ts                   |  7 +++++++
 3 files changed, 32 insertions(+), 8 deletions(-)
 create mode 100644 .changeset/famous-parrots-rush.md

diff --git a/.changeset/famous-parrots-rush.md b/.changeset/famous-parrots-rush.md
new file mode 100644
index 0000000..61eaa41
--- /dev/null
+++ b/.changeset/famous-parrots-rush.md
@@ -0,0 +1,5 @@
+---
+"@rdfjs/types": minor
+---
+
+Add optional direction for literals
diff --git a/data-model.d.ts b/data-model.d.ts
index 50ca6d5..3ecb7d6 100644
--- a/data-model.d.ts
+++ b/data-model.d.ts
@@ -73,6 +73,10 @@ export interface Literal {
      * @link http://tools.ietf.org/html/bcp47
      */
     language: string;
+    /**
+     * the direction of the language-tagged string.
+     */
+    direction?: 'ltr' | 'rtl' | '' | null;
     /**
      * A NamedNode whose IRI represents the datatype of the literal.
      */
@@ -81,7 +85,7 @@ export interface Literal {
     /**
      * @param other The term to compare with.
      * @return True if and only if other has termType "Literal"
-     *                   and the same `value`, `language`, and `datatype`.
+     *                   and the same `value`, `language`, `direction`, and `datatype`.
      */
     equals(other: Term | null | undefined): boolean;
 }
@@ -254,16 +258,19 @@ export interface DataFactory<OutQuad extends BaseQuad = Quad, InQuad extends Bas
     blankNode(value?: string): BlankNode;
 
     /**
-     * @param                 value              The literal value.
-     * @param languageOrDatatype The optional language or datatype.
-     *                                                    If `languageOrDatatype` is a NamedNode,
-     *                                                    then it is used for the value of `NamedNode.datatype`.
-     *                                                    Otherwise `languageOrDatatype` is used for the value
-     *                                                    of `NamedNode.language`.
+     * @param value              The literal value.
+     * @param languageOrDatatype The optional language, datatype, or directional language.
+     *                           If `languageOrDatatype` is a NamedNode,
+     *                           then it is used for the value of `NamedNode.datatype`.
+     *                           If `languageOrDatatype` is a NamedNode, it is used for the value
+     *                           of `NamedNode.language`.
+     *                           Otherwise, it is used as a directional language,
+     *                           from which the language is set to `languageOrDatatype.language`
+     *                           and the direction to `languageOrDatatype.direction`.
      * @return A new instance of Literal.
      * @see Literal
      */
-    literal(value: string, languageOrDatatype?: string | NamedNode): Literal;
+    literal(value: string, languageOrDatatype?: string | NamedNode | DirectionalLanguage): Literal;
 
     /**
      * This method is optional.
@@ -308,3 +315,8 @@ export interface DataFactory<OutQuad extends BaseQuad = Quad, InQuad extends Bas
      */
     fromQuad(original: InQuad): OutQuad;
 }
+
+export interface DirectionalLanguage {
+    language: string;
+    direction?: 'ltr' | 'rtl' | '' | null;
+}
diff --git a/rdf-js-tests.ts b/rdf-js-tests.ts
index 220016f..0579705 100644
--- a/rdf-js-tests.ts
+++ b/rdf-js-tests.ts
@@ -36,6 +36,7 @@ function test_terms() {
     const termType3: string = literal.termType;
     const value3: string = literal.value;
     const language3: string = literal.language;
+    const dir3: 'ltr' | 'rtl' | '' | null | undefined = literal.direction;
     const datatype3: NamedNode = literal.datatype;
     let literalEqual: boolean = literal.equals(someTerm);
     literalEqual = literal.equals(null);
@@ -81,6 +82,12 @@ function test_datafactory() {
     const literal1: Literal = dataFactory.literal('abc');
     const literal2: Literal = dataFactory.literal('abc', 'en-us');
     const literal3: Literal = dataFactory.literal('abc', namedNode);
+    const literal4: Literal = dataFactory.literal('abc', { language: 'en-us' });
+    const literal5: Literal = dataFactory.literal('abc', { language: 'en-us', direction: 'ltr' });
+    const literal6: Literal = dataFactory.literal('abc', { language: 'en-us', direction: 'rtl' });
+    const literal7: Literal = dataFactory.literal('abc', { language: 'en-us', direction: '' });
+    // @ts-expect-error
+    const literal8: Literal = dataFactory.literal('abc', { language: 'en-us', direction: 'wrong' });
 
     const variable: Variable = dataFactory.variable ? dataFactory.variable('v1') : <any> {};