CIDs as interfaces #203
Comments
|
A lot of these want a @Gozala answer |
I think using distinct interface name from class name was good move and removes room for whole lot of confusion. It is also better aligned with the IPLD schemas which uses term I would much rather have discussion about specifics of the That said I'll try to provide some constructive feedback on individual points:
I won't particularity miss those and I got to say I'm ready to let v0 legacy go. As you may have notices I've dropped
This circular reference is a very useful trick for retaining CID-ness when transferring them across JS realms / workers, because circular reference stays intact while class information is lost. This had been a primary motivation while The Given the tradeoffs I still think that
All of the multicodec / multibase stuff uses those names and terms. I'd say stay consistent, yet I would personally not look into updating all the code to change from
I think it useful in interface (as we have some code that uses that for inference) & in implementation it is crucial as it needs to leave out
Previous implementation used to take base names e.g. While I have no personal attachment to this method I believe a lot of nft.storage / web.storage assumes that we can pass
I'm not sure I fully understand this suggestion. With I also can not compare to |
|
I also have to say it is hard not to be frustrated after:
Please don't get this a wrong way, but it's been almost a year now & I can't help but feel that all of this efforts had been a waste of time or worse because bunch of code had been built around upcoming |
|
My constructive suggestion here would be to move along with #199. These breaking changes could be discussed and considered separately. I don't believe existence of |
I think this is completely valid, but I also think the landscape has shifted a bit over the past 12+ months. With the renaming of There's a desire to do something different to That said, maybe it'd be better to just start with toV0/toV1Given how much data is in CIDv0 it's not going away any time soon, but I also don't see us converting between V0 and V1 very often, certainly not often enough to require utility functions like this to be on the interface. Sounds like we agree here. asCID
This is a quite central to the point I think, if it's a useful thing, it could live in a separate file as a util an only imported if required. It doesn't need to be on the interface. toJSON
I didn't see a reason to include it in the interface, it could be something that's an implementation detail. That is, I think an implementation of a Similar to toString
Hopefully type checkers and tests would catch regressions here? It just seems like it could be a concern external to the interface (e.g. the expectation is you operate on the parse/decodeWould still really prefer these methods just said what they did. CIDIface/CIDImpl
This was mostly in response to this comment. The point is by not exporting the default class you don't tie yourself in knots over the names of things. ...
I agree, I don't think #199 should be blocked by this. |
|
@achingbrain I think there are few things to consider here, when thinking about trimming some methods from the interface:
With above rational following fields had been added to
I think
I would like to also address |
I'm constantly making use of this method in my code. 😅 |
From #203 > I would like to also address byteOffset, byteLength fields. I don't think they were a bad idea, it's just I was not allowed to complete implementation of that idea. Given that the feature is incomplete and untested, remove it for now and if it's required it can be implemented fully in the future. Fixes #208 BREAKING CHANGE: The CID class no longer has `.byteOffset` and `.byteLength` properties - these can be accessed via the `.bytes` property instead
From #203 > I would like to also address byteOffset, byteLength fields. I don't think they were a bad idea, it's just I was not allowed to complete implementation of that idea. Given that the feature is incomplete and untested, remove it for now and if it's required it can be implemented fully in the future. Fixes #208 BREAKING CHANGE: The CID class no longer has `.byteOffset` and `.byteLength` properties - these can be accessed via the `.bytes` property instead
This is an attempt at implementing #203, converting the CID class into a minimal interface and having factory functions to return objects that conform to the CID interface. I've preserved all the generics the `Link` interface introduced and there are functions in `link.js` that add the extra methods to turn something that conforms to `CID` into something that can be used as a `Link` so existing code using the `Link` API should not have to change. Notably there was no need to update any of the `Link` tests. The static methods on CID have been exported as individual functions - the names remain the same (`decode`, `parse`, etc) in an attempt to be less disruptive. Code using these methods should mostly just need to change: ```js import { CID } from 'multiformats/cid' ``` to: ```js import * as CID from 'multiformats/cid ``` Types can be imported as: ```ts import type { CID } from 'multiformats/interface' ``` or as before: ```ts import type { CID } from 'multiformats/cid' ``` BREAKING CHANGE: the CID class is now an interface
This is an attempt at implementing #203, converting the CID class into a minimal interface and having factory functions to return objects that conform to the CID interface. I've preserved all the generics the `Link` interface introduced and there are functions in `link.js` that add the extra methods to turn something that conforms to `CID` into something that can be used as a `Link` so existing code using the `Link` API should not have to change. Notably there was no need to update any of the `Link` tests. The static methods on CID have been exported as individual functions - the names remain the same (`decode`, `parse`, etc) in an attempt to be less disruptive. Code using these methods should mostly just need to change: ```js import { CID } from 'multiformats/cid' ``` to: ```js import * as CID from 'multiformats/cid ``` Types can be imported as: ```ts import type { CID } from 'multiformats/interface' ``` or as before: ```ts import type { CID } from 'multiformats/cid' ``` BREAKING CHANGE: the CID class is now an interface
This is an attempt at implementing #203, converting the CID class into a minimal interface and having factory functions to return objects that conform to the CID interface. I've preserved all the generics the `Link` interface introduced and there are functions in `link.js` that add the extra methods to turn something that conforms to `CID` into something that can be used as a `Link` so existing code using the `Link` API should not have to change. Notably there was no need to update any of the `Link` tests. The static methods on CID have been exported as individual functions - the names remain the same (`decode`, `parse`, etc) in an attempt to be less disruptive. Code using these methods should mostly just need to change: ```js import { CID } from 'multiformats/cid' ``` to: ```js import * as CID from 'multiformats/cid ``` Types can be imported as: ```ts import type { CID } from 'multiformats/interface' ``` or as before: ```ts import type { CID } from 'multiformats/cid' ``` BREAKING CHANGE: the CID class is now an interface
This is an attempt at implementing #203, converting the CID class into a minimal interface and having factory functions to return objects that conform to the CID interface. I've preserved all the generics the `Link` interface introduced and there are functions in `link.js` that add the extra methods to turn something that conforms to `CID` into something that can be used as a `Link` so existing code using the `Link` API should not have to change. Notably there was no need to update any of the `Link` tests. The static methods on CID have been exported as individual functions - the names remain the same (`decode`, `parse`, etc) in an attempt to be less disruptive. Code using these methods should mostly just need to change: ```js import { CID } from 'multiformats/cid' ``` to: ```js import * as CID from 'multiformats/cid ``` Types can be imported as: ```ts import type { CID } from 'multiformats/interface' ``` or as before: ```ts import type { CID } from 'multiformats/cid' ``` BREAKING CHANGE: the CID class is now an interface
|
I've taken all the above on board and opened a PR that implements this here for further discussion: #211 |
This is an attempt at implementing #203, converting the CID class into a minimal interface and having factory functions to return objects that conform to the CID interface. I've preserved all the generics the `Link` interface introduced and there are functions in `link.js` that add the extra methods to turn something that conforms to `CID` into something that can be used as a `Link` so existing code using the `Link` API should not have to change. Notably there was no need to update any of the `Link` tests. The static methods on CID have been exported as individual functions - the names remain the same (`decode`, `parse`, etc) in an attempt to be less disruptive. Code using these methods should mostly just need to change: ```js import { CID } from 'multiformats/cid' ``` to: ```js import * as CID from 'multiformats/cid ``` Types can be imported as: ```ts import type { CID } from 'multiformats/interface' ``` or as before: ```ts import type { CID } from 'multiformats/cid' ``` BREAKING CHANGE: the CID class is now an interface
|
Closing for now, I think this is redundant (although I acknowledge that it may not be ideal yet and we may want to make further changes as discussed here) |
#161 was closed and it looks like we've backtracked on the CIDs as interfaces thing. Now we have a
Linkinterface andCIDclass that implements the link interface. We also have CIDs as anArrayBufferViewwhich, I don't know, maybe didn't turn out to be as useful as we thought it might be at the time, but the end result is it has extra propertiesbyteOffsetandbyteLengthwhich are obscured from the uninterested caller by making them non-enumerable. This works but it is very slow.If we're going to town on #199 maybe we could do the CID-as-interface. I'd like to propose a very minimal interface, any static methods would be exposed as named exports instead.
Some thoughts:
toV0/toV1can we live without these? A quick grep of the js-ipfs codebase and we only call them in tests and for top-level UI type output - the cli and the http gateway, would vote to remove and let users have their own utils for thisasCID/isCIDmy (perhaps unpopular) opinion is that these are named too similarly and thatasCIDis clunky to use in practice as it requires null-guarding on the output. If the CID interface is only the fields above perhaps we don't need to convert old impls into new ones any more (the original purpose ofasCIDIIRC)parse/decodevscidFromString/cidFromBytes- the meaning of the words 'parse' and 'decode' are so close as to be synonymous which makes the API hard to use without reference to documentation; let's just say what they do.@libp2p/peer-idhas taken this approach and it makes the codebase a bit more straightforward to the newcomer.toJSONcan we live without this? Similar totoV0andtoV1I only see it used in UIs.toString(encoder?: MultibaseEncoder)omission - maybe if you have a non-default encoder you could just use it to encode the.bytesproperty of theCIDinstead of passing it to thetoStringmethod? Callingcid.toString()would only ever return the default encoding (base58btc for v0, base32 for v1). The current impl maintains a cache of strings which might be a reason to keep it? I am not sure where this has been a bottleneck in the past though.CIDIface/CIDImpl-@multiformats/multiaddrand@libp2p/peer-idhave avoided this sort of naming scheme by intentionally not exporting the default implementation. You only get factory functions that take some input and return something that conforms to the interface. I suggest following that convention here too.The text was updated successfully, but these errors were encountered: