@zimic/http 0.0.1-canary.2

package/src/typegen/openapi/transform/operations.ts

@@ -0,0 +1,120 @@
+import ts from 'typescript';
+
+import { Override } from '@/types/utils';
+import { isDefined } from '@/utils/data';
+
+import { TypeTransformContext } from './context';
+import { normalizeTypeLiteralMethodType } from './methods';
+
+export function createOperationsIdentifierText(serviceName: string) {
+  return `${serviceName}Operations`;
+}
+
+export function createOperationsIdentifier(serviceName: string) {
+  return ts.factory.createIdentifier(createOperationsIdentifierText(serviceName));
+}
+
+type OperationsDeclaration = ts.InterfaceDeclaration;
+
+export function isOperationsDeclaration(node: ts.Node | undefined): node is OperationsDeclaration {
+  return node !== undefined && ts.isInterfaceDeclaration(node) && node.name.text === 'operations';
+}
+
+type Operation = Override<
+  ts.PropertySignature,
+  {
+    type: ts.TypeLiteralNode;
+    name: ts.Identifier | ts.StringLiteral;
+  }
+>;
+
+function isOperation(node: ts.Node): node is Operation {
+  return (
+    ts.isPropertySignature(node) &&
+    (ts.isIdentifier(node.name) || ts.isStringLiteral(node.name)) &&
+    node.type !== undefined &&
+    ts.isTypeLiteralNode(node.type)
+  );
+}
+
+function wrapOperationType(type: ts.TypeLiteralNode, context: TypeTransformContext) {
+  context.typeImports.http.add('HttpSchema');
+
+  const httpSchemaMethodWrapper = ts.factory.createQualifiedName(
+    ts.factory.createIdentifier('HttpSchema'),
+    ts.factory.createIdentifier('Method'),
+  );
+  return ts.factory.createTypeReferenceNode(httpSchemaMethodWrapper, [type]);
+}
+
+function normalizeOperation(operation: ts.TypeElement, context: TypeTransformContext) {
+  /* istanbul ignore if -- @preserve
+   * Operation members are always expected to be an operation. */
+  if (!isOperation(operation)) {
+    return undefined;
+  }
+
+  const newType = normalizeTypeLiteralMethodType(operation.type, context);
+
+  return ts.factory.updatePropertySignature(
+    operation,
+    operation.modifiers,
+    operation.name,
+    operation.questionToken,
+    wrapOperationType(newType, context),
+  );
+}
+
+export function normalizeOperations(operations: OperationsDeclaration, context: TypeTransformContext) {
+  const newIdentifier = createOperationsIdentifier(context.serviceName);
+
+  const newMembers = operations.members.map((operation) => normalizeOperation(operation, context)).filter(isDefined);
+
+  return ts.factory.updateInterfaceDeclaration(
+    operations,
+    operations.modifiers,
+    newIdentifier,
+    operations.typeParameters,
+    operations.heritageClauses,
+    newMembers,
+  );
+}
+
+function removeOperationIfUnreferenced(operation: ts.TypeElement, context: TypeTransformContext) {
+  /* istanbul ignore if -- @preserve
+   * Operation members are always expected to be an operation. */
+  if (!isOperation(operation)) {
+    return undefined;
+  }
+
+  const operationName = operation.name.text;
+  const isReferenced = context.referencedTypes.operations.has(operationName);
+
+  if (isReferenced) {
+    context.referencedTypes.operations.delete(operationName);
+    return operation;
+  }
+
+  return undefined;
+}
+
+export function removeUnreferencedOperations(operations: OperationsDeclaration, context: TypeTransformContext) {
+  const newMembers = operations.members
+    .map((operation) => removeOperationIfUnreferenced(operation, context))
+    .filter(isDefined);
+
+  context.referencedTypes.operations.clear();
+
+  if (newMembers.length === 0) {
+    return undefined;
+  }
+
+  return ts.factory.updateInterfaceDeclaration(
+    operations,
+    operations.modifiers,
+    operations.name,
+    operations.typeParameters,
+    operations.heritageClauses,
+    newMembers,
+  );
+}

package/src/typegen/openapi/transform/paths.ts

@@ -0,0 +1,119 @@
+import ts from 'typescript';
+
+import { Override } from '@/types/utils';
+import { isDefined } from '@/utils/data';
+
+import { renameComponentReferences } from './components';
+import { TypeTransformContext } from './context';
+import { normalizeMethod } from './methods';
+
+export function createPathsIdentifier(serviceName: string) {
+  return ts.factory.createIdentifier(`${serviceName}Schema`);
+}
+
+type PathsDeclaration = ts.InterfaceDeclaration | ts.TypeAliasDeclaration;
+
+export function isPathsDeclaration(node: ts.Node | undefined): node is PathsDeclaration {
+  return (
+    node !== undefined &&
+    (ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node)) &&
+    node.name.text === 'paths'
+  );
+}
+
+type Path = Override<
+  ts.PropertySignature,
+  {
+    type: ts.TypeLiteralNode | ts.IndexedAccessTypeNode;
+    name: ts.Identifier | ts.StringLiteral;
+  }
+>;
+
+function isPath(node: ts.TypeElement): node is Path {
+  return (
+    ts.isPropertySignature(node) &&
+    (ts.isIdentifier(node.name) || ts.isStringLiteral(node.name)) &&
+    node.type !== undefined &&
+    (ts.isTypeLiteralNode(node.type) || ts.isIndexedAccessTypeNode(node.type))
+  );
+}
+
+function normalizePathNameWithParameters(pathName: string) {
+  return pathName.replace(/{([^}]+)}/g, ':$1');
+}
+
+function wrapComponentPathType(type: ts.TypeNode, context: TypeTransformContext) {
+  context.typeImports.http.add('HttpSchema');
+
+  const httpSchemaMethodsWrapper = ts.factory.createQualifiedName(
+    ts.factory.createIdentifier('HttpSchema'),
+    ts.factory.createIdentifier('Methods'),
+  );
+  return ts.factory.createTypeReferenceNode(httpSchemaMethodsWrapper, [type]);
+}
+
+export function normalizePath(
+  path: ts.TypeElement,
+  context: TypeTransformContext,
+  options: { isComponent?: boolean } = {},
+) {
+  const { isComponent = false } = options;
+
+  /* istanbul ignore if -- @preserve
+   * Path members are always expected to be a path. */
+  if (!isPath(path)) {
+    return undefined;
+  }
+
+  const newPathName = isComponent ? path.name.text : normalizePathNameWithParameters(path.name.text);
+  const newIdentifier = isComponent ? path.name : ts.factory.createStringLiteral(newPathName);
+
+  let newType: ts.TypeNode;
+
+  if (ts.isTypeLiteralNode(path.type)) {
+    const newMethods = path.type.members
+      .map((method) => normalizeMethod(method, context, { pathName: newPathName }))
+      .filter(isDefined);
+
+    if (newMethods.length === 0) {
+      return undefined;
+    }
+
+    newType = ts.factory.updateTypeLiteralNode(path.type, ts.factory.createNodeArray(newMethods));
+  } else {
+    newType = renameComponentReferences(path.type, context);
+  }
+
+  return ts.factory.updatePropertySignature(
+    path,
+    path.modifiers,
+    newIdentifier,
+    path.questionToken,
+    isComponent ? wrapComponentPathType(newType, context) : newType,
+  );
+}
+
+function wrapPathsType(type: ts.TypeLiteralNode, context: TypeTransformContext) {
+  context.typeImports.http.add('HttpSchema');
+
+  const httpSchemaPathsWrapper = ts.factory.createIdentifier('HttpSchema');
+  return ts.factory.createTypeReferenceNode(httpSchemaPathsWrapper, [type]);
+}
+
+export function normalizePaths(pathsOrTypeAlias: PathsDeclaration, context: TypeTransformContext) {
+  const newIdentifier = createPathsIdentifier(context.serviceName);
+
+  const paths = ts.isTypeAliasDeclaration(pathsOrTypeAlias)
+    ? ts.factory.createInterfaceDeclaration(pathsOrTypeAlias.modifiers, pathsOrTypeAlias.name, undefined, undefined, [])
+    : pathsOrTypeAlias;
+
+  const newMembers = paths.members.map((path) => normalizePath(path, context)).filter(isDefined);
+  const newType = ts.factory.createTypeLiteralNode(newMembers);
+
+  return ts.factory.createTypeAliasDeclaration(
+    paths.modifiers,
+    newIdentifier,
+    paths.typeParameters,
+    wrapPathsType(newType, context),
+  );
+}

package/src/typegen/openapi/utils/types.ts

@@ -0,0 +1,45 @@
+import ts from 'typescript';
+
+export function isNeverType(type: ts.TypeNode) {
+  return type.kind === ts.SyntaxKind.NeverKeyword;
+}
+
+export function isUnknownType(type: ts.TypeNode) {
+  return type.kind === ts.SyntaxKind.UnknownKeyword;
+}
+
+export function isNumericType(type: ts.TypeNode) {
+  return type.kind === ts.SyntaxKind.NumberKeyword;
+}
+
+export function isBooleanType(type: ts.TypeNode) {
+  return type.kind === ts.SyntaxKind.BooleanKeyword;
+}
+
+export function isNullType(type: ts.TypeNode | ts.LiteralTypeNode['literal']) {
+  return type.kind === ts.SyntaxKind.NullKeyword;
+}
+
+export function createBlobType() {
+  return ts.factory.createTypeReferenceNode('Blob');
+}
+
+export function createNullType() {
+  return ts.factory.createLiteralTypeNode(ts.factory.createNull());
+}
+
+export function createImportSpecifier(importName: string) {
+  return ts.factory.createImportSpecifier(false, undefined, ts.factory.createIdentifier(importName));
+}
+
+export function createImportDeclaration(
+  importSpecifiers: ts.ImportSpecifier[],
+  moduleName: string,
+  options: { typeOnly: boolean },
+) {
+  return ts.factory.createImportDeclaration(
+    undefined,
+    ts.factory.createImportClause(options.typeOnly, undefined, ts.factory.createNamedImports(importSpecifiers)),
+    ts.factory.createStringLiteral(moduleName),
+  );
+}

package/src/types/arrays.d.ts

@@ -0,0 +1,4 @@
+interface ArrayConstructor {
+  // eslint-disable-next-line @typescript-eslint/method-signature-style
+  isArray<Item>(value: unknown): value is Item[];
+}

package/src/types/json.ts

@@ -0,0 +1,89 @@
+type JSON = { [key: string]: JSON } | JSON[] | string | number | boolean | null | undefined;
+
+namespace JSON {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export type Loose = Record<string, any> | Loose[] | string | number | boolean | null | undefined;
+}
+
+/**
+ * Represents or validates a type that is compatible with JSON.
+ *
+ * **IMPORTANT**: the input of `JSONValue` and all of its internal types must be declared inline or as a type aliases
+ * (`type`). They cannot be interfaces.
+ *
+ * @example
+ *   import { type JSONValue } from '@zimic/http';
+ *
+ *   // Can be used as a standalone type:
+ *   const value: JSONValue = {
+ *     name: 'example',
+ *     tags: ['one', 'two'],
+ *   };
+ *
+ * @example
+ *   import { type JSONValue } from '@zimic/http';
+ *
+ *   // Can be used with a type argument to validate a JSON value:
+ *   type ValidJSON = JSONValue<{
+ *     id: string;
+ *     email: string;
+ *     createdAt: string;
+ *   }>;
+ *
+ *   // This results in a type error:
+ *   type InvalidJSON = JSONValue<{
+ *     id: string;
+ *     email: string;
+ *     createdAt: Date; // `Date` is not a valid JSON value.
+ *     save: () => Promise<void>; // Functions are not valid JSON values.
+ *   }>;
+ */
+export type JSONValue<Type extends JSON = JSON> = Type;
+
+export namespace JSONValue {
+  /** A loose version of the JSON value type. JSON objects are not strictly typed. */
+  export type Loose<Type extends JSON.Loose = JSON.Loose> = Type;
+}
+
+/**
+ * Recursively converts a type to its JSON-serialized version. Dates are converted to strings and keys with non-JSON
+ * values are excluded.
+ *
+ * @example
+ *   import { type JSONSerialized } from '@zimic/http';
+ *
+ *   type SerializedUser = JSONSerialized<{
+ *     id: string;
+ *     email: string;
+ *     createdAt: Date;
+ *     save: () => Promise<void>;
+ *   }>;
+ *   // {
+ *   //   id: string;
+ *   //   email: string;
+ *   //   createdAt: string;
+ *   // }
+ */
+export type JSONSerialized<Type> = Type extends JSONValue
+  ? Type
+  : Type extends string | number | boolean | null | undefined
+    ? Type
+    : Type extends Date
+      ? string
+      : Type extends (...parameters: never[]) => unknown
+        ? never
+        : Type extends symbol
+          ? never
+          : Type extends Map<infer _Key, infer _Value>
+            ? Record<string, never>
+            : Type extends Set<infer _Value>
+              ? Record<string, never>
+              : Type extends (infer ArrayItem)[]
+                ? JSONSerialized<ArrayItem>[]
+                : Type extends object
+                  ? {
+                      [Key in keyof Type as [JSONSerialized<Type[Key]>] extends [never] ? never : Key]: JSONSerialized<
+                        Type[Key]
+                      >;
+                    }
+                  : never;

package/src/types/objects.d.ts

@@ -0,0 +1,14 @@
+type ObjectKey<Type> = keyof Type & string;
+type ObjectValue<Type> = Type[ObjectKey<Type>];
+type ObjectEntry<Type> = [ObjectKey<Type>, ObjectValue<Type>];
+
+interface ObjectConstructor {
+  // eslint-disable-next-line @typescript-eslint/method-signature-style
+  keys<Type>(object: Type): ObjectKey<Type>[];
+
+  // eslint-disable-next-line @typescript-eslint/method-signature-style
+  values<Type>(object: Type): ObjectValue<Type>[];
+
+  // eslint-disable-next-line @typescript-eslint/method-signature-style
+  entries<Type>(object: Type): ObjectEntry<Type>[];
+}

package/src/types/requests.ts

@@ -0,0 +1,96 @@
+import { JSONSerialized, JSONValue } from '@/types/json';
+import { HttpStatusCode } from '@/types/schema';
+import { ReplaceBy } from '@/types/utils';
+
+import HttpFormData from '../formData/HttpFormData';
+import { HttpFormDataSchema } from '../formData/types';
+import HttpHeaders from '../headers/HttpHeaders';
+import { HttpHeadersSchema } from '../headers/types';
+import HttpSearchParams from '../searchParams/HttpSearchParams';
+import { HttpSearchParamsSchema } from '../searchParams/types';
+
+/** The body type for HTTP requests and responses. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type HttpBody = JSONValue | HttpFormData<any> | HttpSearchParams<any> | Blob | ArrayBuffer;
+
+export namespace HttpBody {
+  /** A loose version of the HTTP body type. JSON values are not strictly typed. */
+  export type Loose = ReplaceBy<HttpBody, JSONValue, JSONValue.Loose>;
+
+  /** Convert a possibly loose HTTP body to be strictly typed. JSON values are serialized to their strict form. */
+  export type ConvertToStrict<Type> = Type extends Exclude<HttpBody, JSONValue> ? Type : JSONSerialized<Type>;
+}
+
+/**
+ * An HTTP headers object with a strictly-typed schema. Fully compatible with the built-in
+ * {@link https://developer.mozilla.org/docs/Web/API/Headers `Headers`} class.
+ */
+export type StrictHeaders<Schema extends HttpHeadersSchema = HttpHeadersSchema> = Pick<
+  HttpHeaders<Schema>,
+  keyof Headers
+>;
+
+/**
+ * An HTTP search params object with a strictly-typed schema. Fully compatible with the built-in
+ * {@link https://developer.mozilla.org/docs/Web/API/URLSearchParams `URLSearchParams`} class.
+ */
+export type StrictURLSearchParams<Schema extends HttpSearchParamsSchema = HttpSearchParamsSchema> = Pick<
+  HttpSearchParams<Schema>,
+  keyof URLSearchParams
+>;
+
+/**
+ * An HTTP form data object with a strictly-typed schema. Fully compatible with the built-in
+ * {@link https://developer.mozilla.org/docs/Web/API/FormData `FormData`} class.
+ */
+export type StrictFormData<Schema extends HttpFormDataSchema = HttpFormDataSchema> = Pick<
+  HttpFormData<Schema>,
+  keyof FormData
+>;
+
+/**
+ * An HTTP request with a strictly-typed JSON body. Fully compatible with the built-in
+ * {@link https://developer.mozilla.org/docs/Web/API/Request `Request`} class.
+ */
+export interface HttpRequest<
+  StrictBody extends HttpBody.Loose = HttpBody,
+  StrictHeadersSchema extends HttpHeadersSchema = HttpHeadersSchema,
+> extends Request {
+  headers: StrictHeaders<StrictHeadersSchema>;
+  text: () => Promise<StrictBody extends string ? StrictBody : string>;
+  json: () => Promise<StrictBody extends string | Exclude<HttpBody, JSONValue> ? never : StrictBody>;
+  formData: () => Promise<
+    StrictBody extends HttpFormData<infer HttpFormDataSchema>
+      ? StrictFormData<HttpFormDataSchema>
+      : StrictBody extends HttpSearchParams<infer HttpSearchParamsSchema>
+        ? StrictFormData<HttpSearchParamsSchema>
+        : FormData
+  >;
+  clone: () => this;
+}
+
+/**
+ * An HTTP response with a strictly-typed JSON body and status code. Fully compatible with the built-in
+ * {@link https://developer.mozilla.org/docs/Web/API/Response `Response`} class.
+ */
+export interface HttpResponse<
+  StrictBody extends HttpBody.Loose = HttpBody,
+  StatusCode extends number = number,
+  StrictHeadersSchema extends HttpHeadersSchema = HttpHeadersSchema,
+> extends Response {
+  ok: StatusCode extends HttpStatusCode.Information | HttpStatusCode.Success | HttpStatusCode.Redirection
+    ? true
+    : false;
+  status: StatusCode;
+  headers: StrictHeaders<StrictHeadersSchema>;
+  text: () => Promise<StrictBody extends string ? StrictBody : string>;
+  json: () => Promise<StrictBody extends string | Exclude<HttpBody, JSONValue> ? never : StrictBody>;
+  formData: () => Promise<
+    StrictBody extends HttpFormData<infer HttpFormDataSchema>
+      ? StrictFormData<HttpFormDataSchema>
+      : StrictBody extends HttpSearchParams<infer HttpSearchParamsSchema>
+        ? StrictFormData<HttpSearchParamsSchema>
+        : FormData
+  >;
+  clone: () => this;
+}