search

ipld / specs

Content-addressed, authenticated, immutable data structures
Other
592 stars 108 forks source link

Library design recommendations. #241

Closed warpfork closed 4 years ago

warpfork commented 4 years ago

Starting a new folder for this. The content I'm imagining gathering here isn't exactly specs, per se... but it's definitely content that's worth gathering somewhere more centrally than in the comments in the source code of any single implementing library and language.

First up: some remarks on Node and Kind, and how and why regarding Node as an interface becomes systemically important.

I felt this is particularly important to write about because it's quite non-obvious from the first couple of things a new library author is likely to encounter first; it doesn't show up until you start trying to implement some of the more advanced features... but by then it may be too late to address without a painful refactor. So knowing about it earlier is likely to save a great deal of work.

There's probably quite a lot of other content we can gather which is useful recommendations for implementers, but not exactly "spec", which can later flesh out this folder with more content; this nodes-and-kinds doc is just the first thing I come up with.

mikeal commented 4 years ago

Should I add a section on what a good Block interface should be?

warpfork commented 4 years ago

Should I add a section on what a good Block interface should be?

I'd put it in another file. I kinda have one theme that I wanna hammer the crap out of in this file, which is that Node really needs to be an interface or there will be regrets.

warpfork commented 4 years ago

There's a good idea for further followup in @vmx's comment thread -- but I don't wanna do it today / in this PR :sweat_smile:

Any objections on moving this one towards a merge?

rvagg commented 4 years ago

Some small suggestions in my comments. I'm OK with merging this after addressing those.

The most valuable thing from the discussion you and I had about this @warpfork from the JavaScript perspective was the ideas around porcelain vs plumbing which we've totally messed up in JS which leads to a radically different design of ipld-prime vs the APIs we currently have available in JS.

This is a higher-level conern that what you've addressed here so maybe it doesn't belong in this file—or it could go into an intro section. It'd be something like "why we need a Node abstraction around IPLD data" and discuss metadata and state maintenance. That sometimes you just want a native instantiation of some blob of IPLD data (AsObject()) but in doing so, you lose valuable data that you may need for certain workflows and you miss out on efficiency and performance opportunities.

rvagg commented 4 years ago

this also deserves an entry in the main README.md I reckon

warpfork commented 4 years ago

I addressed a bunch of comments, and this has been out for quite a while, so I'm gonna roll forward in accordance with that last ~"lgtm after suggestions" comment and merge this.

I didn't attempt to address that porcelain-vs-plumbing thing @rvagg brought up, but I think it'd be really really excellent to do that in the future.

rvagg commented 4 years ago

some of my recent work even switched to using the "porcelain" terminology .. it wasn't really part of my CS language (aside from git's use of it) but you've colonised my head on this one