no breaking changes

Author: jitsedesmet

packages/rules-sparql-1-2/lib/grammar.ts

@@ -813,8 +813,9 @@ export const iriFull: SparqlGrammarRule<'iriFull', T11.TermIriFull> = {
       const raw = iriToken.image.slice(1, -1);
       return C.astFactory.termNamed(
         C.astFactory.sourceLocation(iriToken),
-        raw.replaceAll(/\\u([0-9a-fA-F]{4})|\\U([0-9a-fA-F]{8})/gu, (_, unicode4, unicode8) =>
-          decodeUchar((unicode4 ?? unicode8))),
+        // TODO: next major replace with implementation of codePointEscape.
+        //  The function no longer serves the intended purpose since it is not reusable for `string`.
+        C.codepointEscape(raw),
       );
     });
   },

packages/rules-sparql-1-2/lib/parserUtils.ts

@@ -3,6 +3,22 @@ import { AstFactory } from './AstFactory.js';
 import type { SparqlContext, SparqlGeneratorContext } from './sparql12HelperTypes.js';
 import type { Sparql12Nodes } from './sparql12Types.js';
 
+/**
+ * Decode UCHAR codepoint escapes (\\uXXXX / \\UXXXXXXXX) within a string according to
+ * [SPARQL 1.2 §19.2](https://www.w3.org/TR/sparql12-query/#sec-escapes).
+ *
+ * Unlike the SPARQL 1.1 variant, this function rejects surrogate code points (U+D800–U+DFFF)
+ * even when they would form a valid surrogate pair.
+ * @deprecated will be removed in next MAJOR in favor of the less usecase dependent {@link decodeUchar}.
+ */
+export function sparql12CodepointEscape(input: string): string {
+  return input.replaceAll(
+    /\\u([0-9a-fA-F]{4})|\\U([0-9a-fA-F]{8})/gu,
+    (_, unicode4: string | undefined, unicode8: string | undefined) =>
+      decodeUchar((unicode4 ?? unicode8)!),
+  );
+}
+
 export function decodeUchar(hex: string): string {
   const codePoint = Number.parseInt(hex, 16);
   if (codePoint >= 0xD800 && codePoint <= 0xDFFF) {
@@ -20,6 +36,10 @@ export function completeParseContext(
     prefixes: Object.assign(Object.create(null), context.prefixes),
     parseMode: context.parseMode ? new Set(context.parseMode) : new Set([ 'canParseVars', 'canCreateBlankNodes' ]),
     skipValidation: context.skipValidation ?? false,
+    /**
+     * @deprecated since it cannot be used for string decoding.
+     */
+    codepointEscape: context.codepointEscape ?? sparql12CodepointEscape,
   };
 }
 

packages/rules-sparql-1-2/lib/sparql12HelperTypes.ts

@@ -52,5 +52,13 @@ export type SparqlGrammarRule<
   ParamType extends any[] = [],
 > = ParserRule<SparqlContext, NameType, ReturnType, ParamType>;
 
-export type SparqlContext = T11.SparqlContext & { astFactory: AstFactory };
+export type SparqlContext = T11.SparqlContext & {
+  astFactory: AstFactory;
+  /**
+   * Function that decodes UCHAR codepoint escapes (\\uXXXX / \\UXXXXXXXX) within a string.
+   * In SPARQL 1.2 this is applied per-rule rather than as a query pre-processor.
+   * @deprecated no longer used since it did not properly implement the decuding of sting literals.
+   */
+  codepointEscape: (input: string) => string;
+};
 export type SparqlGeneratorContext = T11.SparqlGeneratorContext & { astFactory: AstFactory };