HTTP Methods Reference — TypeScript source

// HTTP request-method reference - pure, deterministic data + lookups. No DOM, no
// React. Property flags (safe / idempotent / cacheable / hasBody) follow RFC 9110
// and the MDN reference table.

export interface MethodEntry {
  method: string;
  /** Read-only semantics - no server state change. */
  safe: boolean;
  /** Repeating the call has the same effect as a single call. */
  idempotent: boolean;
  /** Responses may be stored by a cache (per RFC 9110 / MDN). */
  cacheable: boolean;
  /** The method conventionally carries a request body. */
  hasBody: boolean;
  description: string;
  typicalUse: string;
}

/** The nine HTTP request methods (RFC 9110 / 9111). */
export const METHODS: MethodEntry[] = [
  {
    method: 'GET',
    safe: true,
    idempotent: true,
    cacheable: true,
    hasBody: false,
    description: 'Retrieves a representation of the target resource; a read-only request.',
    typicalUse: 'Fetching a web page, reading an API resource, loading an image.',
  },
  {
    method: 'POST',
    safe: false,
    idempotent: false,
    cacheable: true,
    hasBody: true,
    description: 'Submits data to be processed, typically creating a new resource or triggering an action.',
    typicalUse: 'Submitting a form, creating a record, publishing a message.',
  },
  {
    method: 'PUT',
    safe: false,
    idempotent: true,
    cacheable: false,
    hasBody: true,
    description: 'Replaces the target resource entirely with the request body.',
    typicalUse: 'Updating a full record at a known URL, uploading a file by its path.',
  },
  {
    method: 'PATCH',
    safe: false,
    idempotent: false,
    cacheable: false,
    hasBody: true,
    description: 'Applies a partial modification to the target resource.',
    typicalUse: 'Updating one field of a record, toggling a flag.',
  },
  {
    method: 'DELETE',
    safe: false,
    idempotent: true,
    cacheable: false,
    hasBody: false,
    description: 'Removes the target resource.',
    typicalUse: 'Deleting a record or file by its URL.',
  },
  {
    method: 'HEAD',
    safe: true,
    idempotent: true,
    cacheable: true,
    hasBody: false,
    description: 'Identical to GET but returns only the response headers, no body.',
    typicalUse: 'Checking existence, size, or freshness before downloading.',
  },
  {
    method: 'OPTIONS',
    safe: true,
    idempotent: true,
    cacheable: false,
    hasBody: false,
    description: 'Describes the communication options for the target resource.',
    typicalUse: 'CORS preflight requests, discovering allowed methods.',
  },
  {
    method: 'CONNECT',
    safe: false,
    idempotent: false,
    cacheable: false,
    hasBody: false,
    description: 'Establishes a tunnel to the server (used with TLS/HTTPS proxies).',
    typicalUse: 'Proxying encrypted connections through an intermediary.',
  },
  {
    method: 'TRACE',
    safe: true,
    idempotent: true,
    cacheable: false,
    hasBody: false,
    description: 'Performs a message loop-back test along the path to the target (debugging only).',
    typicalUse: 'Diagnosing request transformations by intermediaries.',
  },
];

export interface MethodFilter {
  safe?: boolean;
  idempotent?: boolean;
  cacheable?: boolean;
  /** Free text matched (case-insensitively) against method, description, and typicalUse. */
  query?: string;
}

/** Case-insensitive single-method lookup; returns null when unknown. */
export function getMethod(name: string): MethodEntry | null {
  const n = name.trim().toUpperCase();
  return METHODS.find((m) => m.method === n) ?? null;
}

/**
 * Filter the method set by boolean flags and an optional text query.
 * Omitted flags are ignored; a present flag constrains to that value. An empty
 * query returns the flag-filtered pool unchanged.
 */
export function filterMethods(opts: MethodFilter = {}): MethodEntry[] {
  const q = (opts.query ?? '').trim().toLowerCase();
  return METHODS.filter((m) => {
    if (opts.safe !== undefined && m.safe !== opts.safe) return false;
    if (opts.idempotent !== undefined && m.idempotent !== opts.idempotent) return false;
    if (opts.cacheable !== undefined && m.cacheable !== opts.cacheable) return false;
    if (q) {
      return (
        m.method.toLowerCase().includes(q) ||
        m.description.toLowerCase().includes(q) ||
        m.typicalUse.toLowerCase().includes(q)
      );
    }
    return true;
  });
}

export interface MethodComparison {
  sameSafety: boolean;
  sameIdempotence: boolean;
  differences: string[];
}

/**
 * Compare two methods, surfacing where their semantics agree and differ. The
 * `differences` array lists every mismatched property (safe, idempotent,
 * cacheable, hasBody) as a human-readable sentence. Unknown methods compare as
 * fully-different (no assumptions about their semantics).
 */
export function compareMethods(a: MethodEntry, b: MethodEntry): MethodComparison {
  const differences: string[] = [];
  if (a.safe !== b.safe) {
    differences.push(`${a.method} is ${a.safe ? 'safe' : 'not safe'}, ${b.method} is ${b.safe ? 'safe' : 'not safe'}.`);
  }
  if (a.idempotent !== b.idempotent) {
    differences.push(`${a.method} is ${a.idempotent ? 'idempotent' : 'not idempotent'}, ${b.method} is ${b.idempotent ? 'idempotent' : 'not idempotent'}.`);
  }
  if (a.cacheable !== b.cacheable) {
    differences.push(`${a.method} is ${a.cacheable ? 'cacheable' : 'not cacheable'}, ${b.method} is ${b.cacheable ? 'cacheable' : 'not cacheable'}.`);
  }
  if (a.hasBody !== b.hasBody) {
    differences.push(`${a.method} ${a.hasBody ? 'takes' : 'does not take'} a body, ${b.method} ${b.hasBody ? 'takes' : 'does not take'} a body.`);
  }
  return {
    sameSafety: a.safe === b.safe,
    sameIdempotence: a.idempotent === b.idempotent,
    differences,
  };
}