url-templates 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SorinGFS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Validate a template.
+ * Returns true or throws a detailed error.
+ *
+ * @throws {TypeError | Error}
+ */
+declare function isUrlTemplate(template: string): boolean;
+
+/**
+ * Inspect a template.
+ * Returns the parsed AST.
+ */
+declare function inspect(template: string): any[];
+
+/**
+ * Parse and validate a template.
+ * Returns an object with an expand() method.
+ *
+ * @throws {TypeError | Error}
+ */
+declare function parseTemplate(template: string): { expand(vars?: any): string };
+
+/**
+ * Compile a template without validation.
+ * Returns an object with an expand() method.
+ */
+declare function compile(template: string): { expand(vars?: any): string };
+
+declare const urlTemplates: {
+    isUrlTemplate: typeof isUrlTemplate;
+    inspect: typeof inspect;
+    parseTemplate: typeof parseTemplate;
+    compile: typeof compile;
+};
+
+export = urlTemplates;

package/index.js

@@ -0,0 +1,112 @@
+'use strict';
+// RFC 6570 fully compiant uri-template validator and loader
+const keyOperators = new Set(['?', '&', ';']);
+const operators = new Set(['+', '#', '.', '/', '?', '&', ';']);
+const separator = (operator) => (operator === '' || operator === '+' || operator == '#' ? ',' : operator === '?' ? '&' : operator);
+const isDefined = (value) => value !== undefined && value !== null;
+const encodeUnreserved = (string) => encodeURIComponent(string).replace(/[!'()*]/g, (char) => '%' + char.charCodeAt(0).toString(16).toUpperCase());
+const encodeReserved = (string) => string.split(/(%[0-9A-Fa-f]{2})/g).map((part, i) => (i % 2 ? part : encodeURI(part).replace(/%5B/g, '[').replace(/%5D/g, ']'))).join('');
+const encodeValue = (operator, value, key) => {
+    value = operator === '+' || operator === '#' ? encodeReserved(value) : encodeUnreserved(value);
+    return key ? encodeReserved(key) + '=' + value : value;
+};
+const ast = [];
+// url-template validator
+function isUrlTemplate(template, inspect) {
+    if (typeof template !== 'string') throw new TypeError('uri-template must be a string.');
+    if (!/^[A-Za-z0-9\-._~:/?#\[\]@!$&'()*+,;=%{}]*$/.test(template)) throw new Error('invalid character(s) in uri-template.');
+    for (let i = 0; i < template.length; ) {
+        const start = template.indexOf('{', i);
+        if ((start === -1 && template.indexOf('}', i) > start) || template.indexOf('}', i) < start) throw new Error('unstarted expression in uri-template');
+        if (start === -1) { inspect && ast.push(template.slice(i)); break; }
+        if (inspect && start > i) ast.push(template.slice(i, start));
+        const end = template.indexOf('}', start + 1);
+        if (end === -1) throw new Error('unterminated expression in uri-template.');
+        let expression = template.slice(start + 1, end);
+        if (expression.length === 0) throw new Error('empty expression.');
+        const first = expression[0];
+        const operator = operators.has(first) ? ((expression = expression.slice(1)), first) : '';
+        if (expression.length === 0) throw new Error('expression missing variable names.');
+        const varspecs = expression.split(',').map((key) => {
+            const colon = key.indexOf(':');
+            const limit = colon !== -1 ? Number(key.slice(colon + 1)) : null;
+            if (isDefined(limit) && (limit % 1 !== 0 || isNaN(limit) || limit < 1 || limit > 9999)) throw new Error('invalid limit modifier.');
+            if (limit) key = key.slice(0, colon);
+            const explode = key.endsWith('*');
+            if (explode && limit) throw new Error('invalid modifier having both explode and limit.');
+            if (explode) key = key.slice(0, -1);
+            if (!/^(?:[A-Za-z0-9_]|%[0-9A-Fa-f]{2})+(?:\.(?:[A-Za-z0-9_]|%[0-9A-Fa-f]{2})+)*$/.test(key)) throw new Error('invalid variable name in uri-template.');
+            return Object.assign({ key }, limit ? { limit } : explode ? { explode } : {});
+        });
+        if (inspect) ast.push({ [operator]: varspecs });
+        i = end + 1;
+    }
+    return inspect ? ast : true;
+}
+// url-template filler with optional validation
+function parseTemplate(template, validate) {
+    if (validate) isUrlTemplate(template);
+    return {
+        expand: (vars = {}) =>
+            template.replace(/([^\{\}]+)|\{([^\{\}])([^\{\}]*)\}/g, (match, literal, first, expression) => {
+                if (first + expression) {
+                    const values = [];
+                    const operator = operators.has(first) ? first : ((expression = first + expression), '');
+                    expression.split(/,/g).forEach((variable) => {
+                        const match = /(?<key>[^:\*]*)(?::(?<length>\d+)|(?<explode>\*))?/.exec(variable).groups;
+                        const key = match.key;
+                        const value = vars[key];
+                        if (isDefined(value) && value !== '') {
+                            if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+                                let string = value.toString();
+                                if (match.length) string = string.substring(0, parseInt(match.length));
+                                values.push(encodeValue(operator, string, keyOperators.has(operator) ? key : ''));
+                            } else {
+                                if (validate && match.length) throw new Error('invalid limit modifier on objects.');
+                                if (match.explode) {
+                                    if (Array.isArray(value)) {
+                                        value.filter(isDefined).forEach((item) => values.push(encodeValue(operator, item, keyOperators.has(operator) ? key : '')));
+                                    } else {
+                                        Object.keys(value).forEach((key) => {
+                                            if (isDefined(value[key])) values.push(encodeValue(operator, value[key], key));
+                                        });
+                                    }
+                                } else {
+                                    const array = [];
+                                    if (Array.isArray(value)) {
+                                        value.filter(isDefined).forEach((item) => array.push(encodeValue(operator, item)));
+                                    } else {
+                                        Object.keys(value).forEach((key) => {
+                                            if (isDefined(value[key])) {
+                                                array.push(encodeUnreserved(key));
+                                                array.push(encodeValue(operator, value[key].toString()));
+                                            }
+                                        });
+                                    }
+                                    if (keyOperators.has(operator) && Object.keys(value).length) values.push(encodeUnreserved(key) + '=' + array.join());
+                                    else if (array.length !== 0) values.push(array.join());
+                                }
+                            }
+                        } else {
+                            if (operator === ';') {
+                                if (isDefined(value)) values.push(encodeUnreserved(key));
+                            } else if (value === '' && (operator === '&' || operator === '?')) {
+                                values.push(encodeUnreserved(key) + '=');
+                            } else if (value === '') {
+                                values.push('');
+                            }
+                        }
+                    });
+                    return (operator === '+' || values.length === 0 ? '' : operator) + values.join(separator(operator));
+                }
+                return encodeReserved(literal);
+            }),
+    };
+}
+// export
+module.exports = {
+    parseTemplate: (template) => parseTemplate(template, true),
+    isUrlTemplate: (template) => isUrlTemplate(template),
+    inspect: (template) => isUrlTemplate(template, true),
+    compile: (template) => parseTemplate(template),
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "url-templates",
+  "version": "1.0.0",
+  "description": "A url-template validator, expander and inspector as defined by RFC 6570",
+  "keywords": [
+    "url",
+    "uri",
+    "template",
+    "url-template",
+    "uri-template",
+    "rfc6570",
+    "validation"
+  ],
+  "homepage": "https://github.com/SorinGFS/url-templates#readme",
+  "bugs": {
+    "url": "https://github.com/SorinGFS/url-templates/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SorinGFS/url-templates.git"
+  },
+  "license": "MIT",
+  "author": "SorinGFS",
+  "type": "commonjs",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}

package/readme.md

@@ -0,0 +1,77 @@
+---
+
+title: URL Templates
+
+description: A URL Template validator, expander and inspector
+
+---
+
+## Overview
+
+A URL Template validator, expander and inspector — fully RFC 6570 compliant.
+Passes all the 252 tests from the [uritemplate-test](https://github.com/uri-templates/uritemplate-test) suite. Minimal, zero dependency, sync API; exposes AST for linters/interfaces and both validated and non-validated expansion paths.
+
+## Install
+
+```bash title="console"
+npm i url-templates
+```
+
+## Usage
+
+This library provides the following `url-template` functions:
+
+### Validation
+
+```js title="js"
+const { isUrlTemplate } = require('url-templates');
+try {
+    console.log('valid:', isUrlTemplate('/users/{id}')); // true
+} catch (error) {
+    console.error('invalid:', error.message);
+}
+```
+
+**Note:**
+It returns `true` or throws an `error`.
+
+### Inspection
+
+```js title="js"
+const { inspect } = require('url-templates');
+try {
+    console.dir(inspect('/search{?q*,lang:2}'), { depth: null }); 
+    // [ '/search', { '?': [ { key: 'q', explode: true }, { key: 'lang', limit: 2 } ] } ]
+} catch (error) {
+    console.error('invalid:', error.message);
+}
+```
+
+**Note:**
+Same as with `isUrlTemplate`, but if valid returns the parsed `AST` instead of `true`.
+
+### Expansion with validation
+
+```js title="js"
+const { parseTemplate } = require('url-templates');
+try {
+    console.log(parseTemplate('/items/{id}').expand({ id: 42 })); // '/items/42'
+} catch (error) {
+    console.error('parse/validation error:', error.message);
+}
+```
+
+**Note:**
+If valid returns the `expand(vars)` function which returns the expanded `url-template`. Otherwise, it throws an `error`. The `expand` function also throws `error` if `limit` is defined on `objects` (`isUrlTemplate` function cannot know that without runtime vars).
+
+### Expansion without validation
+
+```js title="js"
+const { compile } = require('url-templates');
+console.log(compile('/broken{').expand({})); // returns '/broken{'; invalid parts left for postprocessing
+console.log(compile('/good{id}').expand({id:42})); // returns '/good42'; 
+```
+
+**Note:**
+Returns a usable expander without validation (for cases where validation is done elsewhere, or for the cases where some sort of postprocessing will follow).
+