@c9up/ream 0.2.13 → 0.2.15

package/src/graphql/GraphQLEngine.ts

@@ -182,7 +182,7 @@ export interface ResolverOptions {
 interface ResolverEntry {
   typeName: string
   fieldName: string
-  handlerClass: new (...args: unknown[]) => Record<string, (...args: unknown[]) => unknown>
+  handlerClass: abstract new (...args: never[]) => object
   methodName: string
   options: ResolverOptions
 }
@@ -204,7 +204,7 @@ export interface SelectionField {
 export class GraphQLEngine {
   #schemaSource: string
   #resolvers: Map<string, ResolverEntry> = new Map()
-  #container?: { make<T>(target: new (...args: unknown[]) => T): Promise<T> }
+  #container?: { make<T>(target: abstract new (...args: never[]) => T): Promise<T> }
   readonly path: string
   #playground: boolean
   #maxQueryBytes: number
@@ -239,7 +239,9 @@ export class GraphQLEngine {
   }
 
   /** Set IoC container for resolver instantiation. */
-  useContainer(container: { make<T>(target: new (...args: unknown[]) => T): Promise<T> }): void {
+  useContainer(container: {
+    make<T>(target: abstract new (...args: never[]) => T): Promise<T>
+  }): void {
     this.#container = container
   }
 
@@ -247,7 +249,7 @@ export class GraphQLEngine {
   resolver(
     typeName: string,
     fieldName: string,
-    handlerClass: new (...args: unknown[]) => Record<string, (...args: unknown[]) => unknown>,
+    handlerClass: abstract new (...args: never[]) => object,
     methodName: string,
     options?: ResolverOptions,
   ): void {
@@ -369,11 +371,13 @@ export class GraphQLEngine {
 
     try {
       // Resolve handler via IoC or direct instantiation.
-      const instance = this.#container
+      // `Reflect.construct`, not `new`: the resolver may be an abstract class,
+      // which the runtime builds happily and `new` refuses at compile time.
+      const instance: object = this.#container
         ? await this.#container.make(entry.handlerClass)
-        : new entry.handlerClass()
+        : Reflect.construct(entry.handlerClass, [])
 
-      const handler = instance[entry.methodName]
+      const handler = Reflect.get(instance, entry.methodName)
       if (typeof handler !== 'function') {
         return {
           ok: false,

package/src/helpers/bytes.ts

@@ -18,6 +18,11 @@ const UNITS = {
 
 type Unit = keyof typeof UNITS
 
+/** A suffix the table knows. Checked, so nothing has to be asserted. */
+function isUnit(value: string): value is Unit {
+  return value in UNITS
+}
+
 const PARSE = /^((?:-|\+)?(?:\d+(?:\.\d+)?)) *(kb|mb|gb|tb|pb)$/i
 /** Trailing `.00`, or the zeros trailing a real decimal. */
 const TRAILING_ZEROS = /(?:\.0*|(\.[^0]+)0+)$/
@@ -33,10 +38,16 @@ export function parse(value: string | number): number | null {
   if (typeof value !== 'string') return null
 
   const matched = PARSE.exec(value)
-  const amount = matched ? Number.parseFloat(matched[1]) : Number.parseInt(value, 10)
+  // Both groups are required by the pattern, so a match carries both — but
+  // read as `matched[2]` the second was typed "a string, or nothing", and the
+  // `as Unit` that followed asserted past exactly that. Named, with the
+  // suffix checked against the table it indexes, nothing is asserted.
+  const [, digits, suffix] = matched ?? []
+  const amount = digits !== undefined ? Number.parseFloat(digits) : Number.parseInt(value, 10)
   if (Number.isNaN(amount)) return null
 
-  const unit = (matched ? matched[2].toLowerCase() : 'b') as Unit
+  const unit = suffix === undefined ? 'b' : suffix.toLowerCase()
+  if (!isUnit(unit)) return null
   return Math.floor(UNITS[unit] * amount)
 }
 

package/src/helpers/string.ts

@@ -214,9 +214,9 @@ export function pluralize(word: string, count?: number): string {
  * @example humanize('user_name') // 'User name'
  */
 export function humanize(s: string): string {
-  const words = splitWords(s)
-  if (words.length === 0) return ''
-  return [words[0]?.charAt(0).toUpperCase() + words[0]?.slice(1), ...words.slice(1)].join(' ')
+  const [first, ...rest] = splitWords(s)
+  if (first === undefined) return ''
+  return [first.charAt(0).toUpperCase() + first.slice(1), ...rest].join(' ')
 }
 
 // ---------------------------------------------------------------------------

package/src/http/Exception.ts

@@ -315,8 +315,10 @@ export class ExceptionHandler extends Macroable {
   #expandStatusPages(): Record<number, StatusPageRenderer> {
     if (!this.#expandedStatusPages) {
       const expanded: Record<number, StatusPageRenderer> = {}
-      for (const range of Object.keys(this.statusPages)) {
-        Object.assign(expanded, parseStatusRange(range, this.statusPages[range]))
+      // `entries` rather than `keys` plus a lookup: the value comes back
+      // already known to be there, instead of read again as maybe-missing.
+      for (const [range, renderer] of Object.entries(this.statusPages)) {
+        Object.assign(expanded, parseStatusRange(range, renderer))
       }
       this.#expandedStatusPages = expanded
     }
@@ -440,13 +442,17 @@ export class ExceptionHandler extends Macroable {
   /**
    * Pick a renderer by content negotiation.
    *
-   * DEVIATION (named): ream lists `json` FIRST, so a request with no or `*` /`*`
-   * Accept defaults to JSON (API-first). AdonisJS lists `html` first
-   * (full-stack default). Explicit `text/html` / `vnd.api+json` are honoured
-   * identically.
+   * `html` is listed first, as AdonisJS does, so a request that states no
+   * preference — no `Accept` at all, or `*` /`*` — gets the error page rather
+   * than a JSON body. A browser always sends `text/html` and an API client
+   * always asks for JSON, so the order only decides for the clients in
+   * between: curl, a health probe, a proxy that stripped the header. For a
+   * framework that ships a view layer, a page is the better answer there.
+   *
+   * The fallback stays JSON, for a client that accepts none of the three.
    */
   async renderError(error: HttpError, ctx: HttpContext): Promise<void> {
-    switch (ctx.request.accepts(['json', 'html', 'application/vnd.api+json'])) {
+    switch (ctx.request.accepts(['html', 'json', 'application/vnd.api+json'])) {
       case 'application/vnd.api+json':
         return this.renderErrorAsJSONAPI(error, ctx)
       case 'html':
@@ -458,7 +464,7 @@ export class ExceptionHandler extends Macroable {
 
   /** Pick a validation renderer by content negotiation. */
   async renderValidationError(error: HttpError, ctx: HttpContext): Promise<void> {
-    switch (ctx.request.accepts(['json', 'html', 'application/vnd.api+json'])) {
+    switch (ctx.request.accepts(['html', 'json', 'application/vnd.api+json'])) {
       case 'application/vnd.api+json':
         return this.renderValidationErrorAsJSONAPI(error, ctx)
       case 'html':

package/src/http/Request.ts

@@ -272,7 +272,10 @@ export class Request extends Macroable {
   host(): string | null {
     if (this.#trustProxy) {
       const forwarded = this.#raw.headers['x-forwarded-host']
-      if (forwarded) return forwarded.split(',')[0].trim()
+      // The first hop in the list, named rather than indexed: `split` always
+      // yields one element, and saying so beats being told it might not.
+      const [first] = forwarded?.split(',') ?? []
+      if (first !== undefined) return first.trim()
     }
     return this.#raw.headers.host ?? null
   }
@@ -285,7 +288,8 @@ export class Request extends Macroable {
   protocol(): string {
     if (this.#trustProxy) {
       const forwarded = this.#raw.headers['x-forwarded-proto']
-      if (forwarded) return forwarded.split(',')[0].trim().toLowerCase()
+      const [first] = forwarded?.split(',') ?? []
+      if (first !== undefined) return first.trim().toLowerCase()
     }
     return this.#raw.scheme ?? 'http'
   }
@@ -900,9 +904,8 @@ export class Request extends Macroable {
     fieldName: string,
     options?: import('../bodyparser/MultipartFile.js').FileValidationOptions,
   ): import('../bodyparser/MultipartFile.js').MultipartFile | null {
-    const files = this.#files.get(fieldName)
-    if (!files || files.length === 0) return null
-    const file = files[0]
+    const [file] = this.#files.get(fieldName) ?? []
+    if (file === undefined) return null
     if (options) file.validate(options)
     return file
   }

package/src/http/Response.ts

@@ -11,10 +11,10 @@ import { randomUUID } from 'node:crypto'
 import { createReadStream } from 'node:fs'
 import { readFile, stat } from 'node:fs/promises'
 import { basename } from 'node:path'
-import etag from 'etag'
-import { contentType } from 'mime-types'
 import { ReamError } from '../errors/ReamError.js'
 import { durationToSeconds } from '../helpers/duration.js'
+import { etag, matchesIfNoneMatch } from './etag.js'
+import { contentType } from './mime.js'
 
 /**
  * Default ceiling on a buffered response body — the same 100MB the Rust layer
@@ -738,12 +738,8 @@ export class Response extends Macroable {
     if (!((status >= 200 && status < 300) || status === 304)) return false
     const noneMatch = this.#request?.header('if-none-match')
     const currentEtag = this.getHeader('etag')
-    if (!noneMatch || !currentEtag) return false
-    if (noneMatch.trim() === '*') return true
-    return noneMatch.split(',').some((tag) => {
-      const t = tag.trim()
-      return t === currentEtag || t === `W/${currentEtag}` || `W/${t}` === currentEtag
-    })
+    if (!currentEtag) return false
+    return matchesIfNoneMatch(noneMatch, currentEtag)
   }
 
   /**

package/src/http/SseStream.ts

@@ -106,13 +106,22 @@ export class SseStream {
         // stop the timer and run close listeners once, so a dropped-
         // at-open stream can't leave an orphaned keepalive ticking
         // against a dead registry slot.
-        void this.#backend.writeStream(this.id, ':keepalive\n\n').then((ok) => {
-          if (!ok && this.#open) {
-            this.#open = false
-            this.#stopPing()
-            this.#fireClose()
-          }
-        })
+        //
+        // A REJECTION means the same thing as `false` and is treated the same
+        // way. It was unhandled before, and an unhandled rejection from a
+        // detached timer takes the whole process down on a default Node —
+        // one client's socket dying would have ended every other client's.
+        void this.#backend
+          .writeStream(this.id, ':keepalive\n\n')
+          .then((ok) => ok)
+          .catch(() => false)
+          .then((ok) => {
+            if (!ok && this.#open) {
+              this.#open = false
+              this.#stopPing()
+              this.#fireClose()
+            }
+          })
       }, ping)
       // The keepalive must not pin the Node event loop — letting the
       // process exit on its own when nothing else is keeping it busy

package/src/http/etag.ts

@@ -0,0 +1,68 @@
+/**
+ * Entity tags, computed here rather than pulled in.
+ *
+ * The `etag` package is fifteen lines of hashing behind a dependency, and this
+ * is the whole of what a response needs. The format is reproduced byte for
+ * byte on purpose: an ETag is a cache key, and changing its shape would
+ * invalidate every cached response in flight the day it shipped.
+ *
+ * `<hex length>-<27 chars of base64 sha1>`, quoted, with `W/` in front when
+ * the caller asks for a weak one. The empty body has a fixed answer because
+ * hashing nothing is the same work every time.
+ */
+
+import { createHash } from 'node:crypto'
+
+/** base64 sha1 of the empty string, truncated as below — precomputed. */
+const EMPTY = '"0-2jmj7l5rSw0yVb/vlWAYkK/YBwk"'
+
+/** The tag for a response body (`etag` package parity, string or Buffer). */
+export function etag(body: string | Buffer, options?: { weak?: boolean }): string {
+  const tag = body.length === 0 ? EMPTY : entityTag(body)
+  return options?.weak === true ? `W/${tag}` : tag
+}
+
+function entityTag(body: string | Buffer): string {
+  const hash = createHash('sha1')
+    .update(typeof body === 'string' ? Buffer.from(body, 'utf8') : body)
+    .digest('base64')
+    .slice(0, 27)
+  // Byte length, not character count: a multi-byte body is longer on the wire
+  // than its string length says.
+  const length = typeof body === 'string' ? Buffer.byteLength(body, 'utf8') : body.length
+  return `"${length.toString(16)}-${hash}"`
+}
+
+/**
+ * The tag for a file, from its metadata rather than its bytes.
+ *
+ * `W/"<size hex>-<mtime hex>"`, which is what the `etag` package produces for
+ * a `Stats` and therefore what Express's `send` — and so every static file
+ * server people have cached against — puts on a static asset. Weak because it
+ * is derived from metadata: two files with the same size and mtime are
+ * equivalent for caching, not provably byte-identical.
+ *
+ * The quotes are not decoration. RFC 9110 §8.8.3 defines an entity-tag as a
+ * quoted string, and a bare hex digest is not one: a strict cache is entitled
+ * to ignore it, which turns every conditional request back into a full
+ * transfer.
+ */
+export function statTag(stat: { size: number; mtimeMs: number }): string {
+  return `W/"${stat.size.toString(16)}-${Math.floor(stat.mtimeMs).toString(16)}"`
+}
+
+/**
+ * Whether `If-None-Match` covers `tag` (RFC 9110 §13.1.2).
+ *
+ * The header is a LIST, and it is compared with the WEAK comparison function —
+ * `W/"x"` and `"x"` match. Raw string equality against the whole header value
+ * failed a client that sent two tags, and failed every client that sent back
+ * the weak form of a strong tag, so both re-downloaded a file they already had.
+ */
+export function matchesIfNoneMatch(header: string | undefined, tag: string): boolean {
+  if (!header || tag === '') return false
+  if (header.trim() === '*') return true
+  const bare = (value: string): string => (value.startsWith('W/') ? value.slice(2) : value)
+  const current = bare(tag)
+  return header.split(',').some((candidate) => bare(candidate.trim()) === current)
+}