Intent to Prototype: FileSystemHandle Unique IDs

Skip to first unread message

Austin Sullivan

Aug 12, 2022, 1:15:58 PM8/12/22
to blink-dev, Joshua Bell, Ayu Ishii, Daseul Lee

Contact emails



FileSystemHandle::getUniqueId() generates a uniquely identifying string which can be used as a key, such as for IndexedDB or WebLocks. Currently, FileSystemHandle objects can be serialized by the browser to be stored as values in IndexedDB, but there is no way to generate a string which is guaranteed to be uniquely identifying.

Developers have complained that building rich experiences on top of the File System Access API is challenging due to the inability to uniquely identify (and index on) handles. Several partners have requested this.

Blink component


TAG review

TAG review status



Interoperability and Compatibility

Gecko: No signal

WebKit: No signal

Web developers: Positive (

Other signals:



Will this feature be supported on all six Blink platforms (Windows, Mac, Linux, Chrome OS, Android, and Android WebView)?

This feature will be supported on all platforms is shipped (currently only desktop platforms)

Is this feature fully tested by web-platform-tests?

The feature will be fully testable with WPT. They'll be written as part of the prototype

Flag name


Tracking bug

Estimated milestones

No milestones specified

Link to entry on the Chrome Platform Status

This intent message was generated by Chrome Platform Status.

Mike West

Aug 16, 2022, 4:07:03 AM8/16/22
to blink-dev, Austin Sullivan, Joshua Bell, Ayu Ishii, Daseul Lee
Hi! I've skimmed through the explainer, but I feel like I'm missing something important. Can you help me understand the difference between the scheme proposed here on the one hand, and relying on something like Crypto.randomUUID() on the other? I don't understand the requirements that would make the latter unworkable, but I'd like to before we add another identifier-generator to the platform. :)



Austin Sullivan

Aug 16, 2022, 2:24:01 PM8/16/22
to Mike West, blink-dev, Joshua Bell, Ayu Ishii, Daseul Lee
Hi Mike,

Good question!

To explain it a different way... why do we need an isSameEntry() method? Why can't we just compare two FileSystemHandle objects directly?

Well, a handle mostly just represents a path on disk (which we never want to expose to a site). The API has a number of ways (drag & drop, file picker, file handling, re-hydration from IndexedDB) to acquire a handle. Two handles acquired from different contexts (possibly at various times, across browsing sessions) may represent the same path and should be considered equal. Only the browser knows where this file actually lives on disk, so only it can determine equality.

We essentially have the same problem here. We can create a unique ID using crypto.randomUUID(), but if we want it to represent the idea of a path on disk and not just a one-way mapping to an arbitrary FileSystemHandle object, we need the browser's help (or to call isSameEntry() on an unbounded number of handles (yikes)).

To make this a bit more concrete, let's consider an example from the Storing a representation of a handle in the database of your choice use case described in the explainer. Say you're a site which allows users to maintain a digital database of their baseball cards. The user selects an image file of the card. You generate an ID using crypto.randomUUID() which represents the file to use as a key in your database alongside all the card's information. You can access the handle using this key with a constant-time lookup in IndexedDB.

A week later, the user logs back on and selects a file from the picker. Is this card already in the database? Your only way to find out is to enumerate all handles you have access to (which could be thousands and thousands of cards) and call isSameEntry() on each of them. The ID you generated is useless until you find the handle in IndexedDB (i.e. handle -> database is potentially a prohibitively expensive operation).

The getUniqueId() method addresses this by answering the "have I seen this handle before" question in constant time.

Ajay Rahatekar

Sep 7, 2022, 4:20:54 PM9/7/22
to blink-dev, Austin Sullivan, blink-dev, Joshua Bell,, Daseul Lee,
+Ajay Rahatekar
Reply all
Reply to author
0 new messages