0
# Utility Functions
1

2
Utility functions for schema manipulation, MIME type detection, and OpenAPI processing tasks.
3

4
## Capabilities
5

6
### Schema Definition Finder
7

8
Find and retrieve schema definitions from OpenAPI documents using JSON Pointer references.
9

10
```typescript { .api }
11
/**
12
 * Find a schema definition by JSON Pointer reference
13
 * @param ref - JSON Pointer reference string (e.g., "#/components/schemas/User")
14
 * @param api - OpenAPI document to search within
15
 * @returns The referenced schema object or undefined if not found
16
 */
17
function findSchemaDefinition(ref: string, api: OASDocument): any;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { findSchemaDefinition } from "oas/utils";
24

25
const api = {
26
  openapi: "3.1.0",
27
  info: { title: "API", version: "1.0.0" },
28
  components: {
29
    schemas: {
30
      User: {
31
        type: "object",
32
        properties: {
33
          id: { type: "string" },
34
          name: { type: "string" }
35
        }
36
      }
37
    }
38
  },
39
  paths: {}
40
};
41

42
// Find schema by reference
43
const userSchema = findSchemaDefinition("#/components/schemas/User", api);
44
console.log(userSchema.properties.name); // { type: "string" }
45

46
// Handle missing references
47
const missing = findSchemaDefinition("#/components/schemas/NotFound", api);
48
console.log(missing); // undefined
49
```
50

51
### MIME Type Matchers
52

53
Collection of utility functions for matching and detecting various MIME types.
54

55
```typescript { .api }
56
const matchesMimeType: {
57
  /**
58
   * Check if MIME type is form URL encoded
59
   * @param mimeType - MIME type string to check
60
   * @returns True if matches application/x-www-form-urlencoded
61
   */
62
  formUrlEncoded(mimeType: string): boolean;
63
  
64
  /**
65
   * Check if content type is JSON
66
   * @param contentType - Content type string to check  
67
   * @returns True if matches JSON content types
68
   */
69
  json(contentType: string): boolean;
70
  
71
  /**
72
   * Check if content type is multipart
73
   * @param contentType - Content type string to check
74
   * @returns True if matches multipart content types
75
   */
76
  multipart(contentType: string): boolean;
77
  
78
  /**
79
   * Check if content type uses wildcards
80
   * @param contentType - Content type string to check
81
   * @returns True if contains wildcard patterns
82
   */
83
  wildcard(contentType: string): boolean;
84
  
85
  /**
86
   * Check if content type is XML
87
   * @param contentType - Content type string to check
88
   * @returns True if matches XML content types
89
   */
90
  xml(contentType: string): boolean;
91
};
92
```
93

94
**Usage Examples:**
95

96
```typescript
97
import { matchesMimeType } from "oas/utils";
98

99
// Check content types
100
const isJson = matchesMimeType.json("application/json"); // true
101
const isJsonApi = matchesMimeType.json("application/vnd.api+json"); // true
102
const isXml = matchesMimeType.xml("application/xml"); // true
103
const isForm = matchesMimeType.formUrlEncoded("application/x-www-form-urlencoded"); // true
104
const isMultipart = matchesMimeType.multipart("multipart/form-data"); // true
105
const hasWildcard = matchesMimeType.wildcard("text/*"); // true
106

107
// Use in operation content type detection
108
function getResponseFormat(contentType: string): string {
109
  if (matchesMimeType.json(contentType)) return "JSON";
110
  if (matchesMimeType.xml(contentType)) return "XML";
111
  if (matchesMimeType.multipart(contentType)) return "Multipart";
112
  if (matchesMimeType.formUrlEncoded(contentType)) return "Form";
113
  return "Unknown";
114
}
115
```
116

117
### JSON Schema Types
118

119
Mapping of OpenAPI document keys to their corresponding JSON Schema type strings.
120

121
```typescript { .api }
122
/**
123
 * JSON Schema type mappings for OpenAPI document properties
124
 */
125
const jsonSchemaTypes: Record<keyof OASDocument, string>;
126
```
127

128
**Usage Examples:**
129

130
```typescript
131
import { jsonSchemaTypes } from "oas/utils";
132

133
// Access type mappings
134
console.log(jsonSchemaTypes.openapi); // "string"
135
console.log(jsonSchemaTypes.info); // "object"
136
console.log(jsonSchemaTypes.servers); // "array"
137
console.log(jsonSchemaTypes.paths); // "object"
138
console.log(jsonSchemaTypes.components); // "object"
139

140
// Use for validation or schema generation
141
function validateOpenAPIProperty(key: keyof OASDocument, value: any): boolean {
142
  const expectedType = jsonSchemaTypes[key];
143
  const actualType = typeof value;
144
  
145
  if (expectedType === "array") {
146
    return Array.isArray(value);
147
  }
148
  
149
  return actualType === expectedType;
150
}
151
```
152

153
### Supported HTTP Methods
154

155
Readonly array of HTTP methods supported by OpenAPI specifications.
156

157
```typescript { .api }
158
/**
159
 * Array of HTTP methods supported in OpenAPI path operations
160
 */
161
const supportedMethods: readonly string[];
162
```
163

164
**Usage Examples:**
165

166
```typescript
167
import { supportedMethods } from "oas/utils";
168

169
// Check supported methods
170
console.log(supportedMethods);
171
// ["get", "put", "post", "delete", "options", "head", "patch", "trace"]
172

173
// Validate HTTP methods
174
function isValidMethod(method: string): boolean {
175
  return supportedMethods.includes(method.toLowerCase());
176
}
177

178
// Filter operations by supported methods
179
function getValidOperations(pathItem: any): Record<string, any> {
180
  const validOps: Record<string, any> = {};
181
  
182
  for (const method of supportedMethods) {
183
    if (pathItem[method]) {
184
      validOps[method] = pathItem[method];
185
    }
186
  }
187
  
188
  return validOps;
189
}
190

191
// Generate operation summaries
192
supportedMethods.forEach(method => {
193
  console.log(`${method.toUpperCase()} operations supported`);
194
});
195
```
196

197
## Type Definitions
198

199
```typescript { .api }
200
// Re-exported for convenience
201
type OASDocument = (OpenAPIV3_1.Document | OpenAPIV3.Document) & Record<string, unknown>;
202
```
203

204
## Import Statement
205

206
```typescript
207
import { 
208
  findSchemaDefinition, 
209
  matchesMimeType, 
210
  jsonSchemaTypes, 
211
  supportedMethods 
212
} from "oas/utils";
213
```