0
# HTTP Field Management
1

2
HTTP field handling for headers and trailers with case-insensitive operations and value management. Fields represent name-value pairs transmitted in HTTP messages with support for multiple values and different placement positions.
3

4
## Capabilities
5

6
### Field Class
7

8
Represents a single HTTP field (header or trailer) with name-value pairs. All field names are case insensitive and support multiple values.
9

10
```typescript { .api }
11
/**
12
 * A name-value pair representing a single field transmitted in an HTTP Request or Response.
13
 * The kind dictates metadata placement within an HTTP message.
14
 * All field names are case insensitive.
15
 */
16
class Field {
17
  readonly name: string;
18
  readonly kind: FieldPosition;
19
  values: string[];
20
  
21
  constructor(options: FieldOptions);
22
  add(value: string): void;
23
  set(values: string[]): void;
24
  remove(value: string): void;
25
  toString(): string;
26
  get(): string[];
27
}
28

29
interface FieldOptions {
30
  name: string;
31
  kind?: FieldPosition;
32
  values?: string[];
33
}
34
```
35

36
**Usage Examples:**
37

38
```typescript
39
import { Field } from "@smithy/protocol-http";
40
import { FieldPosition } from "@smithy/types";
41

42
// Create a header field
43
const contentType = new Field({
44
  name: "Content-Type",
45
  kind: FieldPosition.HEADER,
46
  values: ["application/json"]
47
});
48

49
// Add additional values
50
contentType.add("charset=utf-8");
51
console.log(contentType.toString()); // "application/json, charset=utf-8"
52

53
// Replace all values
54
contentType.set(["text/html"]);
55
console.log(contentType.get()); // ["text/html"]
56

57
// Remove specific values
58
contentType.add("application/json");
59
contentType.remove("text/html");
60
console.log(contentType.get()); // ["application/json"]
61
```
62

63
### Add Value
64

65
Appends a value to the field's value list.
66

67
```typescript { .api }
68
/**
69
 * Appends a value to the field.
70
 * @param value - The value to append
71
 */
72
add(value: string): void;
73
```
74

75
### Set Values
76

77
Overwrites existing field values with new values.
78

79
```typescript { .api }
80
/**
81
 * Overwrite existing field values.
82
 * @param values - The new field values
83
 */
84
set(values: string[]): void;
85
```
86

87
### Remove Value
88

89
Removes all matching entries from the value list.
90

91
```typescript { .api }
92
/**
93
 * Remove all matching entries from list.
94
 * @param value - Value to remove
95
 */
96
remove(value: string): void;
97
```
98

99
### String Representation
100

101
Gets comma-delimited string representation of field values. Values with spaces or commas are automatically double-quoted.
102

103
```typescript { .api }
104
/**
105
 * Get comma-delimited string.
106
 * @returns String representation of Field
107
 */
108
toString(): string;
109
```
110

111
### Get Values
112

113
Returns the field values as an array of strings.
114

115
```typescript { .api }
116
/**
117
 * Get string values as a list
118
 * @returns Values in Field as a list
119
 */
120
get(): string[];
121
```
122

123
### Fields Collection Class
124

125
Collection of Field entries mapped by name with case-insensitive access and filtering capabilities.
126

127
```typescript { .api }
128
/**
129
 * Collection of Field entries mapped by name.
130
 */
131
class Fields {
132
  constructor(options: FieldsOptions);
133
  setField(field: Field): void;
134
  getField(name: string): Field | undefined;
135
  removeField(name: string): void;
136
  getByType(kind: FieldPosition): Field[];
137
}
138

139
interface FieldsOptions {
140
  fields?: Field[];
141
  encoding?: string;
142
}
143
```
144

145
**Usage Examples:**
146

147
```typescript
148
import { Field, Fields } from "@smithy/protocol-http";
149
import { FieldPosition } from "@smithy/types";
150

151
// Create fields collection
152
const headerField = new Field({
153
  name: "Accept",
154
  kind: FieldPosition.HEADER,
155
  values: ["application/json"]
156
});
157

158
const trailerField = new Field({
159
  name: "Status",  
160
  kind: FieldPosition.TRAILER,
161
  values: ["complete"]
162
});
163

164
const fields = new Fields({
165
  fields: [headerField, trailerField],
166
  encoding: "utf-8"
167
});
168

169
// Access fields (case insensitive)
170
const accept = fields.getField("accept");
171
const acceptCaps = fields.getField("ACCEPT"); // Same field
172

173
// Get fields by type
174
const headers = fields.getByType(FieldPosition.HEADER);
175
const trailers = fields.getByType(FieldPosition.TRAILER);
176

177
// Modify collection
178
fields.removeField("status");
179
```
180

181
### Set Field
182

183
Sets or updates a field entry in the collection using the field's name as the key.
184

185
```typescript { .api }
186
/**
187
 * Set entry for a Field name. The name attribute will be used to key the collection.
188
 * @param field - The Field to set
189
 */
190
setField(field: Field): void;
191
```
192

193
### Get Field
194

195
Retrieves a field entry by name with case-insensitive matching.
196

197
```typescript { .api }
198
/**
199
 * Retrieve Field entry by name.
200
 * @param name - The name of the Field entry to retrieve
201
 * @returns The Field if it exists
202
 */
203
getField(name: string): Field | undefined;
204
```
205

206
### Remove Field
207

208
Deletes a field entry from the collection by name.
209

210
```typescript { .api }
211
/**
212
 * Delete entry from collection.
213
 * @param name - Name of the entry to delete
214
 */
215
removeField(name: string): void;
216
```
217

218
### Get Fields by Type
219

220
Helper function for retrieving fields of a specific type (headers or trailers).
221

222
```typescript { .api }
223
/**
224
 * Helper function for retrieving specific types of fields.
225
 * Used to grab all headers or all trailers.
226
 * @param kind - FieldPosition of entries to retrieve
227
 * @returns The Field entries with the specified FieldPosition
228
 */
229
getByType(kind: FieldPosition): Field[];
230
```
231

232
## Types
233

234
```typescript { .api }
235
interface FieldOptions {
236
  name: string;
237
  kind?: FieldPosition;
238
  values?: string[];
239
}
240

241
interface FieldsOptions {
242
  fields?: Field[];
243
  encoding?: string;
244
}
245
```