search

oddsdk / ts-odd

An SDK for building apps with decentralized identity and storage.
https://odd.dev/
Apache License 2.0
179 stars 24 forks source link

WNFS File metadata usage should be documented #381

Open jessmartin opened 2 years ago

jessmartin commented 2 years ago

NB: Feature requests will only be considered if they solve a pain

Summary

Problem

It's possible (I think) to add custom metadata to files through WNFS, but it's not documented anywhere. In fact, the SDK API docs for .add make it look like it's not possible.

Impact

It's unclear how to accomplish certain features without file metadata. This appears to be supported, but undocumented, creating confusion for onboarding developers.

Solution

Create a documentation page in the Guide under the Webnative SDK documenting how to interact with metadata.

Detail

jessmartin commented 2 years ago

From @icidasset:

Even though the Metadata object is of a fixed type, it should be possible to add custom values to it (though you should test that to be sure). The type check just checks if the necessary properties are there: https://github.com/fission-suite/webnative/blob/main/src/fs/types/check.ts#L62 Types and functions: https://github.com/fission-suite/webnative/blob/main/src/fs/metadata.ts#L22

jessmartin commented 2 years ago

@icidasset points out that metadata wasn't designed to be a general-purpose data structure for storing file metadata:

We didn't really design this to have custom metadata. I suppose we always imagined if a user wanted metadata with the file, they'd store it in the file itself or along side of it, instead of using the internal metadata object. We should discuss this as a group for WNFS v2.

To be clear, this Issue isn't intended to be a suggestion that we add and document support for metadata within WNFS. Let's make that design decision, "discuss this as a group", as you say, and then document our conclusion.

Regardless though, if we expect developers to handle their own metadata, we should explicitly state that in the Guide.

For my particular use case, I'm going to have my files handle their own metadata. That seems like a better design decision for data portability / longevity.

Moreover, it should be noted that the current way the code is structured confuses the issue: it doesn't reveal our intention about how/if the metadata should be used. Should probably add code comments around those constructs as well so that when developers stumble across them, they understand why they are there.