Skip to content

Rename requestFileHandles() (plural) to requestFileHandle() (singular) #61

Closed

Description

@tomayac

Summary

All known real-world implementations of the COS API call requestFileHandles() with exactly one hash and read back exactly one handle. The plural form is never used as intended. This issue proposes renaming the method to requestFileHandle() (singular) to better match actual usage.

Evidence

A broad code search across GitHub (31 total results) was conducted across all known independent implementations. Every single call site passes a single-element array and reads back a single handle:

Repo Pattern used
huggingface/transformers.js const [handle] = await ...requestFileHandles([hash])
ngxson/wllama const [handle] = await ...requestFileHandles([hash])
flutter/flutter const [handle] = await ...requestFileHandles([hash])
apache/tvm const handles = await ...requestFileHandles([hash]); const handle = handles[0]
mlc-ai/relax const handles = await ...requestFileHandles([hash]); const handle = handles[0]
GoogleChromeLabs/web-ai-demos const [handle] = await ...requestFileHandles([hash])
Emscripten (tomayac/emscripten PR #27066) requestFileHandles([cosHash])

Zero implementations pass more than one hash in a single call.

Problems with the current plural form

  1. Misleading ergonomics. Every consumer is forced to write const [handle] = await ...requestFileHandles([singleHash]) — wrapping a single item in an array only to destructure it back out is pure boilerplate noise.
  2. False promise of batching. The plural signature implies atomicity or efficiency gains from batching multiple hashes, but no implementer found this useful. AI model files are large and handled one at a time.
  3. Explicit workarounds. The TVM family explicitly does const handles = ...; const handle = handles[0] — actively fighting the plural shape.
  4. Precedent. Web APIs conventionally reflect actual usage. If batching is ever needed in the future, a separate method or overload can be introduced.

Proposal

Rename the method:

// Before
Promise<sequence<FileSystemFileHandle>> requestFileHandles(
  sequence<HashDescriptor> hashes,
  optional CrossOriginStorageOptions options = {}
);

// After
Promise<FileSystemFileHandle> requestFileHandle(
  HashDescriptor hash,
  optional CrossOriginStorageOptions options = {}
);

Callers wanting multiple handles in parallel can use Promise.all(), which is idiomatic JS and gives better per-file error granularity.

References

  • huggingface/transformers.js PR #1549
  • ngxson/wllama PR #248
  • flutter/flutter PR #184149
  • mlc-ai/web-llm PR #748
  • apache/tvm web/src/artifact_cache.ts
  • emscripten-core/emscripten PR #27066

Activity

  1. self-assigned this
    on Jun 15, 2026
  2. beaufortfrancois commented on Jun 15, 2026

    @beaufortfrancois
    Collaborator

    +1

  3. 16 remaining items

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions