capns 0.32.9247

package/README.md

@@ -0,0 +1,130 @@
+# Cap URN - JavaScript Implementation
+
+JavaScript implementation of Cap URN (Capability Uniform Resource Names), built on [Tagged URN](../tagged-urn-js/).
+
+## Features
+
+- **Required Direction Specifiers** - `in`/`out` tags for input/output media types
+- **Media URN Validation** - Validates direction spec values are valid Media URNs
+- **Cross-Language Compatible** - Identical behavior to Rust, Go, and Objective-C implementations
+- **Production Ready** - No fallbacks, fails hard on invalid input
+
+## Installation
+
+```bash
+npm install capns
+```
+
+## Quick Start
+
+```javascript
+const { CapUrn, CapUrnBuilder, CapMatcher } = require('capns');
+
+// Create from string (with required direction specifiers)
+const cap = CapUrn.fromString('cap:in="media:type=binary;v=1";op=extract;out="media:type=object;v=1"');
+console.log(cap.toString());
+
+// Use builder pattern
+const built = new CapUrnBuilder()
+  .inSpec('media:type=void;v=1')
+  .outSpec('media:type=object;v=1')
+  .tag('op', 'generate')
+  .tag('target', 'thumbnail')
+  .build();
+
+// Matching
+const request = CapUrn.fromString('cap:in="media:type=binary;v=1";op=extract;out="media:type=object;v=1"');
+console.log(cap.matches(request)); // true
+
+// Find best match by specificity
+const caps = [
+  CapUrn.fromString('cap:in=*;op=extract;out=*'),
+  CapUrn.fromString('cap:in="media:type=binary;v=1";op=extract;out="media:type=object;v=1"'),
+  CapUrn.fromString('cap:ext=pdf;in="media:type=binary;v=1";op=extract;out="media:type=object;v=1"')
+];
+const best = CapMatcher.findBestMatch(caps, request);
+console.log(best.toString()); // Most specific match
+```
+
+## API Reference
+
+### CapUrn Class
+
+#### Static Methods
+- `CapUrn.fromString(s)` - Parse Cap URN from string
+  - Throws `CapUrnError` on invalid format or missing direction specifiers
+
+#### Instance Methods
+- `toString()` - Get canonical string representation
+- `getTag(key)` - Get tag value (case-insensitive)
+- `getInSpec()` - Get input media type
+- `getOutSpec()` - Get output media type
+- `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 cap matches another
+- `canHandle(request)` - Check if this cap can handle a request
+- `specificity()` - Get specificity score for matching
+- `isMoreSpecificThan(other)` - Compare specificity
+- `equals(other)` - Check equality
+
+### CapUrnBuilder Class
+
+Fluent builder for constructing Cap URNs:
+
+```javascript
+const cap = new CapUrnBuilder()
+  .inSpec('media:type=binary;v=1')
+  .outSpec('media:type=object;v=1')
+  .tag('op', 'extract')
+  .tag('target', 'metadata')
+  .build();
+```
+
+### CapMatcher Class
+
+Utility for matching sets of caps:
+
+- `CapMatcher.findBestMatch(caps, request)` - Find most specific match
+- `CapMatcher.findAllMatches(caps, request)` - Find all matches (sorted by specificity)
+
+### Error Handling
+
+```javascript
+const { CapUrnError, ErrorCodes } = require('capns');
+
+try {
+  const cap = CapUrn.fromString('cap:op=extract'); // Missing in/out
+} catch (error) {
+  if (error instanceof CapUrnError) {
+    console.log(`Error code: ${error.code}`); // MISSING_IN_SPEC
+  }
+}
+```
+
+Cap-specific error codes:
+- `ErrorCodes.MISSING_IN_SPEC` - Missing required `in` tag
+- `ErrorCodes.MISSING_OUT_SPEC` - Missing required `out` tag
+- `ErrorCodes.INVALID_MEDIA_URN` - Invalid Media URN in direction spec
+
+For base Tagged URN error codes, see [Tagged URN documentation](../tagged-urn-js/).
+
+## Documentation
+
+- [RULES.md](./RULES.md) - Cap-specific rules
+- [Tagged URN RULES.md](../tagged-urn-js/RULES.md) - Base format rules (case, quoting, wildcards, etc.)
+
+## Testing
+
+```bash
+npm test
+```
+
+## Cross-Language Compatibility
+
+This JavaScript implementation produces identical results to:
+- [Rust reference implementation](../capns/)
+- [Go implementation](../capns-go/)
+- [Objective-C implementation](../capns-objc/)
+
+All implementations pass the same test cases and follow identical rules.

package/RULES.md

@@ -0,0 +1,55 @@
+# Cap URN Rules (JavaScript)
+
+## Overview
+
+Cap URNs extend Tagged URNs with capability-specific requirements. For base Tagged URN format rules (case handling, tag ordering, wildcards, quoting, value-less tags, etc.), see [Tagged URN RULES.md](../tagged-urn-js/RULES.md).
+
+This document covers only cap-specific rules.
+
+## Cap-Specific Rules
+
+### 1. Required Direction Specifiers
+
+Cap URNs **must** include `in` and `out` tags that specify input/output media types:
+
+```javascript
+// Valid cap URN with direction specifiers
+const cap = CapUrn.fromString('cap:in="media:type=binary;v=1";op=extract;out="media:type=object;v=1"');
+
+// Invalid - missing direction specifiers
+CapUrn.fromString('cap:op=extract'); // throws ErrorCodes.MISSING_IN_SPEC
+```
+
+### 2. No Value-less Tags
+
+Unlike base Tagged URNs which allow value-less tags, Cap URNs require explicit `key=value` format for all tags.
+
+### 3. Media URN Validation
+
+Direction specifier values must be valid Media URNs or wildcard `*`:
+
+```javascript
+// Valid: Media URN value
+'cap:in="media:type=binary;v=1";op=extract;out="media:type=object;v=1"'
+
+// Valid: Wildcard
+'cap:in=*;op=extract;out=*'
+
+// Invalid: Not a Media URN
+'cap:in=binary;op=extract;out=object' // throws ErrorCodes.INVALID_MEDIA_URN
+```
+
+## Cap-Specific Error Codes
+
+| Code | Name | Description |
+|------|------|-------------|
+| 10 | MISSING_IN_SPEC | Cap URN missing required `in` tag |
+| 11 | MISSING_OUT_SPEC | Cap URN missing required `out` tag |
+| 12 | INVALID_MEDIA_URN | Direction spec value is not a valid Media URN |
+
+## Cross-Language Compatibility
+
+This JavaScript implementation follows the same rules as:
+- [Rust reference implementation](../capns/)
+- [Go implementation](../capns-go/)
+- [Objective-C implementation](../capns-objc/)