0
# URI Templates (RFC 6570)
1

2
Support for URI Template expansion according to RFC 6570 specification with variable substitution and expression parsing.
3

4
## Capabilities
5

6
### URITemplate Constructor
7

8
```javascript { .api }
9
/**
10
 * Create URI template instance for expansion
11
 * @param expression - URI template expression string
12
 * @returns URITemplate instance
13
 */
14
function URITemplate(expression: string): URITemplate;
15
```
16

17
### Instance Methods
18

19
```javascript { .api }
20
/**
21
 * Expand template with data variables
22
 * @param data - Object containing template variables
23
 * @param opts - Expansion options
24
 * @returns Expanded URI string
25
 */
26
URITemplate.prototype.expand(data: object, opts?: object): string;
27

28
/**
29
 * Parse template into component parts
30
 * @returns Parsed template structure
31
 */
32
URITemplate.prototype.parse(): object;
33
```
34

35
### Static Methods
36

37
```javascript { .api }
38
/**
39
 * Expand parsed template expression
40
 * @param expression - Parsed template expression
41
 * @param data - Variable data object
42
 * @param opts - Expansion options
43
 * @returns Expanded string
44
 */
45
URITemplate.expand(expression: object, data: object, opts?: object): string;
46

47
/**
48
 * Expand named variables
49
 * @param d - Variable data
50
 * @param options - Variable options
51
 * @param explode - Whether to explode arrays/objects
52
 * @param separator - Separator character
53
 * @param length - Length limit
54
 * @param name - Variable name
55
 * @returns Expanded string
56
 */
57
URITemplate.expandNamed(d: any, options: object, explode: boolean, separator: string, length: number, name: string): string;
58

59
/**
60
 * Expand unnamed variables
61
 * @param d - Variable data
62
 * @param options - Variable options
63
 * @param explode - Whether to explode arrays/objects
64
 * @param separator - Separator character
65
 * @param length - Length limit
66
 * @returns Expanded string
67
 */
68
URITemplate.expandUnnamed(d: any, options: object, explode: boolean, separator: string, length: number): string;
69

70
/**
71
 * Restore previous URITemplate variable
72
 * @returns Previous URITemplate variable value
73
 */
74
URITemplate.noConflict(): any;
75
```
76

77
### URI Integration
78

79
```javascript { .api }
80
/**
81
 * Expand URI template and return URI instance
82
 * @param expression - URI template expression
83
 * @param data - Template variables
84
 * @returns URI instance with expanded template
85
 */
86
URI.expand(expression: string, data: object): URI;
87
```
88

89
**Usage Examples:**
90

91
```javascript
92
// Import URITemplate
93
import URITemplate from 'urijs/src/URITemplate';
94

95
// Basic template expansion
96
const template = new URITemplate('/users/{id}');
97
const expanded = template.expand({ id: '123' });
98
console.log(expanded); // '/users/123'
99

100
// Multiple variables
101
const apiTemplate = new URITemplate('/api/{version}/users/{id}{?fields*}');
102
const apiExpanded = apiTemplate.expand({
103
  version: 'v1',
104
  id: '456',
105
  fields: ['name', 'email', 'created']
106
});
107
console.log(apiExpanded); // '/api/v1/users/456?fields=name,email,created'
108

109
// Query parameter expansion
110
const queryTemplate = new URITemplate('/search{?q,limit,offset}');
111
const queryExpanded = queryTemplate.expand({
112
  q: 'javascript',
113
  limit: 10,
114
  offset: 20
115
});
116
console.log(queryExpanded); // '/search?q=javascript&limit=10&offset=20'
117

118
// Path segment explosion
119
const pathTemplate = new URITemplate('/files{/path*}');
120
const pathExpanded = pathTemplate.expand({
121
  path: ['docs', 'api', 'reference.html']
122
});
123
console.log(pathExpanded); // '/files/docs/api/reference.html'
124

125
// Fragment expansion
126
const fragmentTemplate = new URITemplate('/page{#section}');
127
const fragmentExpanded = fragmentTemplate.expand({
128
  section: 'introduction'
129
});
130
console.log(fragmentExpanded); // '/page#introduction'
131

132
// Complex object expansion
133
const complexTemplate = new URITemplate('/api{/segments*}{?params*}');
134
const complexExpanded = complexTemplate.expand({
135
  segments: ['v2', 'users', '789'],
136
  params: {
137
    include: 'profile',
138
    format: 'json'
139
  }
140
});
141
console.log(complexExpanded); // '/api/v2/users/789?include=profile&format=json'
142

143
// Use with URI.js integration
144
const uriFromTemplate = URI.expand('/api/{version}/users/{id}', {
145
  version: 'v1',
146
  id: '123'
147
});
148
console.log(uriFromTemplate.toString()); // '/api/v1/users/123'
149
uriFromTemplate.addQuery('expand', 'profile');
150
console.log(uriFromTemplate.toString()); // '/api/v1/users/123?expand=profile'
151

152
// Reserved character expansion
153
const reservedTemplate = new URITemplate('/search{/term}{?q}');
154
const reservedExpanded = reservedTemplate.expand({
155
  term: 'hello world',
156
  q: 'special&chars'
157
});
158
console.log(reservedExpanded); // '/search/hello%20world?q=special%26chars'
159

160
// Length-limited expansion
161
const limitTemplate = new URITemplate('/short{/name:3}');
162
const limitExpanded = limitTemplate.expand({
163
  name: 'verylongname'
164
});
165
console.log(limitExpanded); // '/short/ver'
166

167
// Form-style query expansion
168
const formTemplate = new URITemplate('/form{?data*}');
169
const formExpanded = formTemplate.expand({
170
  data: {
171
    firstName: 'John',
172
    lastName: 'Doe',
173
    age: 30
174
  }
175
});
176
console.log(formExpanded); // '/form?firstName=John&lastName=Doe&age=30'
177
```
178

179
### Static Properties
180

181
```javascript { .api }
182
// Template cache for performance
183
URITemplate._cache: object;
184

185
// Regular expressions for parsing
186
URITemplate.EXPRESSION_PATTERN: RegExp;
187
URITemplate.VARIABLE_PATTERN: RegExp;
188
URITemplate.VARIABLE_NAME_PATTERN: RegExp;
189
URITemplate.LITERAL_PATTERN: RegExp;
190
```
191

192
**Advanced Usage Examples:**
193

194
```javascript
195
// Access template cache
196
console.log(URITemplate._cache); // Object with cached templates
197

198
// Parse template manually
199
const template = new URITemplate('/api/{version}/users{?limit,offset}');
200
const parsed = template.parse();
201
console.log(parsed); // Parsed template structure
202

203
// Custom template parsing
204
const customExpression = '{+path}/file{.ext}';
205
const customTemplate = new URITemplate(customExpression);
206
const customResult = customTemplate.expand({
207
  path: 'docs/api',
208
  ext: 'json'
209
});
210
console.log(customResult); // 'docs/api/file.json'
211

212
// Handle undefined variables
213
const undefinedTemplate = new URITemplate('/api/{version}/users/{id?}');
214
const undefinedResult = undefinedTemplate.expand({
215
  version: 'v1'
216
  // id is undefined
217
});
218
console.log(undefinedResult); // '/api/v1/users/'
219

220
// Use with different variable prefixes
221
const prefixTemplate = new URITemplate('/api{/segments*}{?query*}{#fragment}');
222
const prefixResult = prefixTemplate.expand({
223
  segments: ['v1', 'users'],
224
  query: { limit: 10 },
225
  fragment: 'results'
226
});
227
console.log(prefixResult); // '/api/v1/users?limit=10#results'
228
```