tagged-urn 1.0.0

package/README.md

@@ -0,0 +1,158 @@
+# Tagged URN - JavaScript Implementation
+
+Production-ready JavaScript implementation of Tagged URN with strict validation and matching rules.
+
+## Features
+
+- **Strict Rule Enforcement** - Follows exact same rules as Rust, Go, and Objective-C implementations
+- **Case Insensitive** - All input normalized to lowercase
+- **Tag Order Independent** - Canonical alphabetical sorting
+- **Wildcard Support** - `*` matching in values only
+- **Value-less Tags** - Tags without values (`tag`) are wildcards (`tag=*`)
+- **Extended Characters** - Support for `/` and `:` in tag components
+- **Production Ready** - No fallbacks, fails hard on invalid input
+- **Comprehensive Tests** - Full test suite verifying all rules
+
+## Installation
+
+```bash
+npm install tagged-urn
+```
+
+## Quick Start
+
+```javascript
+const { TaggedUrn, TaggedUrnBuilder, UrnMatcher } = require('tagged-urn');
+
+// Create from string
+const urn = TaggedUrn.fromString('cap:op=generate;ext=pdf');
+console.log(urn.toString()); // "cap:ext=pdf;op=generate"
+
+// Use builder pattern
+const built = new TaggedUrnBuilder()
+  .tag('op', 'extract')
+  .tag('target', 'metadata')
+  .build();
+
+// Matching
+const request = TaggedUrn.fromString('cap:op=generate');
+console.log(urn.matches(request)); // true
+
+// Find best match
+const urns = [
+  TaggedUrn.fromString('cap:op=*'),
+  TaggedUrn.fromString('cap:op=generate'),
+  TaggedUrn.fromString('cap:op=generate;ext=pdf')
+];
+const best = UrnMatcher.findBestMatch(urns, request);
+console.log(best.toString()); // "cap:ext=pdf;op=generate" (most specific)
+```
+
+## API Reference
+
+### TaggedUrn Class
+
+#### Static Methods
+- `TaggedUrn.fromString(s)` - Parse Tagged URN from string
+  - Throws `TaggedUrnError` on invalid format
+
+#### Instance Methods
+- `toString()` - Get canonical string representation
+- `getTag(key)` - Get tag value (case-insensitive)
+- `hasTag(key, value)` - Check if tag exists with value
+- `withTag(key, value)` - Add/update tag (returns new instance)
+- `withoutTag(key)` - Remove tag (returns new instance)
+- `matches(other)` - Check if this URN matches another
+- `canHandle(request)` - Check if this URN can handle a request
+- `specificity()` - Get specificity score for matching
+- `isMoreSpecificThan(other)` - Compare specificity
+- `isCompatibleWith(other)` - Check compatibility
+- `equals(other)` - Check equality
+
+### TaggedUrnBuilder Class
+
+Fluent builder for constructing Tagged URNs:
+
+```javascript
+const urn = new TaggedUrnBuilder()
+  .tag('op', 'generate')
+  .tag('format', 'json')
+  .build();
+```
+
+### UrnMatcher Class
+
+Utility for matching sets of Tagged URNs:
+
+- `UrnMatcher.findBestMatch(urns, request)` - Find most specific match
+- `UrnMatcher.findAllMatches(urns, request)` - Find all matches (sorted by specificity)
+- `UrnMatcher.areCompatible(urns1, urns2)` - Check if URN sets are compatible
+
+### Error Handling
+
+```javascript
+const { TaggedUrnError, ErrorCodes } = require('tagged-urn');
+
+try {
+  const urn = TaggedUrn.fromString('invalid:format');
+} catch (error) {
+  if (error instanceof TaggedUrnError) {
+    console.log(`Error code: ${error.code}`);
+    console.log(`Message: ${error.message}`);
+  }
+}
+```
+
+Error codes:
+- `ErrorCodes.INVALID_FORMAT` - General format error
+- `ErrorCodes.MISSING_CAP_PREFIX` - Missing "cap:" prefix
+- `ErrorCodes.INVALID_CHARACTER` - Invalid characters in tags
+- `ErrorCodes.DUPLICATE_KEY` - Duplicate tag keys
+- `ErrorCodes.NUMERIC_KEY` - Pure numeric tag keys
+- `ErrorCodes.EMPTY_TAG` - Empty tag components
+
+## Rules
+
+This implementation strictly follows the 21 Tagged URN rules. See `RULES.md` for complete specification.
+
+### Key Rules Summary:
+
+1. **Case Insensitive** - `cap:OP=Generate` == `cap:op=generate`
+2. **Order Independent** - `cap:a=1;b=2` == `cap:b=2;a=1`
+3. **Prefix Required** - Must start with `cap:`
+4. **Semicolon Separated** - Tags separated by `;`
+5. **Optional Trailing `;`** - `cap:a=1;` == `cap:a=1`
+6. **Canonical Form** - Lowercase, alphabetically sorted, no trailing `;`
+7. **Wildcard Values** - `*` allowed in values only, not keys
+8. **Extended Characters** - `/` and `:` allowed in tag components
+9. **No Duplicate Keys** - Fails hard on duplicates
+10. **No Numeric Keys** - Pure numeric keys forbidden
+
+## Testing
+
+```bash
+npm test
+```
+
+Runs comprehensive test suite covering all rules and edge cases.
+
+## Browser Support
+
+Works in both Node.js and browsers:
+
+```html
+<script src="tagged-urn.js"></script>
+<script>
+const urn = TaggedUrn.fromString('cap:op=generate');
+console.log(urn.toString());
+</script>
+```
+
+## Cross-Language Compatibility
+
+This JavaScript implementation produces identical results to:
+- [Rust implementation](../tagged-urn-rs/)
+- [Go implementation](../tagged-urn-go/)
+- [Objective-C implementation](../tagged-urn-objc/)
+
+All implementations pass the same test cases and follow identical rules.

package/RULES.md

@@ -0,0 +1,92 @@
+# Tagged URN Rules
+
+## Definitive specification for Tagged URN format and behavior
+
+### 1. Case Insensitivity
+Tagged URNs are case insensitive. All input is normalized to lowercase for storage and comparison.
+
+### 2. Tag Order Independence
+The order of tags in the URN string does not matter. Tags are always sorted alphabetically by key in canonical form.
+
+### 3. Mandatory Prefix
+Tagged URNs must always be preceded by `cap:` which is the signifier of a tagged URN.
+
+### 4. Tag Separator
+Tags are separated by semicolons (`;`).
+
+### 5. Trailing Semicolon Optional
+Presence or absence of the final trailing semicolon does not matter. Both `cap:key=value` and `cap:key=value;` are equivalent.
+
+### 6. Character Restrictions
+- No spaces in tagged URNs
+- Allowed characters in tag keys and values: alphanumeric, dashes (`-`), underscores (`_`), slashes (`/`), colons (`:`), dots (`.`), and asterisk (`*` in values only)
+- Quote marks (`"`, `'`), hash (`#`), and other special characters are not accepted
+
+### 7. Tag Structure
+- Tag separator within a tag: `=` separates tag key from tag value
+- Tag separator between tags: `;` separates key-value pairs
+- After the initial `cap:` prefix, colons (`:`) are treated as normal characters, not separators
+
+### 8. No Special Tags
+No reserved tag names - anything goes for tag keys.
+
+### 9. Canonical Form
+The canonical form of Tagged URNs is all lowercase, with tags sorted by keys alphabetically, and no final trailing semicolon.
+
+### 10. Wildcard Support
+- Wildcard `*` is accepted only as tag value, not as tag key
+- When used as a tag value, `*` matches any value for that tag key
+
+### 11. Value-less Tags (Existence Assertion)
+- Tags may be specified without a value: `cap:key1=value1;optimize;key2=value2`
+- A value-less tag like `optimize` is equivalent to `optimize=*` (wildcard)
+- This asserts that the tag exists but matches any value
+- Value-less tags are useful as flags or for checking tag existence
+- **Parsing:** `tag` (no `=`) is parsed as `tag=*`
+- **Serialization:** `tag=*` is serialized as just `tag` (no `=*`)
+- **Note:** `tag=` (explicit `=` with no value) is still an error - this is different from a value-less tag
+
+### 12. Matching Specificity
+As more tags are specified, URNs become more specific:
+- `cap:` matches any URN
+- `cap:prop=*` matches any URN that has a `prop` tag with any value
+- `cap:prop=1` matches only URNs that have `prop=1`, regardless of other tags
+
+### 13. Exact Tag Matching
+`cap:prop=1` matches only URNs that have `prop=1` irrespective of other tags present.
+
+### 14. Subset Matching
+Only the tags specified in the criteria affect matching. URNs with extra tags not mentioned in the criteria still match if they satisfy all specified criteria.
+
+### 15. Duplicate Keys
+Duplicate keys in the same URN result in an error - last occurrence does not win.
+
+### 16. UTF-8 Support
+Full UTF-8 character support within the allowed character set restrictions.
+
+### 17. Numeric Values
+- Tag keys cannot be pure numeric
+- Tag values can be pure numeric
+
+### 18. Empty Tagged URN
+`cap:` with no tags is valid and means "matches all URNs" (universal matcher).
+
+### 19. Length Restrictions
+No explicit length restrictions, though practical limits exist based on URL and system constraints (typically ~2000 characters).
+
+### 20. Wildcard Restrictions
+Asterisk (`*`) in tag keys is not valid. Asterisk is only valid in tag values to signify wildcard matching.
+
+### 21. Colon Treatment
+Forward slashes (`/`) and colons (`:`) are valid anywhere in tag components and treated as normal characters, except for the mandatory `cap:` prefix which is not part of the tag structure.
+
+## Implementation Notes
+
+- All implementations must normalize input to lowercase
+- All implementations must sort tags alphabetically in canonical output
+- All implementations must handle trailing semicolons consistently
+- All implementations must validate character restrictions identically
+- All implementations must implement matching logic identically
+- All implementations must reject duplicate keys with appropriate error messages
+- All implementations must parse value-less tags as wildcard (`tag` → `tag=*`)
+- All implementations must serialize wildcard tags as value-less (`tag=*` → `tag`)

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "tagged-urn",
+  "version": "1.0.0",
+  "description": "JavaScript implementation of Tagged URN with strict validation and matching",
+  "main": "tagged-urn.js",
+  "scripts": {
+    "test": "node tagged-urn.test.js"
+  },
+  "keywords": [
+    "tagged-urn",
+    "urn",
+    "namespace",
+    "validation",
+    "matching"
+  ],
+  "author": "Bahram Joharshamshiri",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jowharshamshiri/tagged-urn.git",
+    "directory": "tagged-urn-js"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "files": [
+    "tagged-urn.js",
+    "tagged-urn.test.js",
+    "RULES.md",
+    "README.md"
+  ]
+}