denoland / denoland/deploy_feedback

[KV Feedback]: Documentation

Open
#374 0 comments 4 reactions 0 assignees View on GitHub
kv
Dominant language
No language data
Stars
79
Forks
5
PR merge metrics
No merged PRs in 30d

Description

### Type of feedback

Documentation improvement

### Description

While waiting on the beta acceptance, I've compiled my feedback on the available documentation.

### API feedback

#### Deno.AtomicOperation
* could be made more user friendly with an example or examples around the benefits of using atomic transactions and what problem they solve. There's a great example in the Transaction page in the runtime manual, maybe link to it?
* the docs for 'sum', 'max' and 'min' refer to 'Shortcut for creating a sum/max/min mutation'. It took me awhile to understand this is a shortcut to KvMutation.sum/max/min. The docs should reference and/or hyperlink to this.

#### Deno.Kv
* I'm unclear if calling kv.close() on exit is best practice or even necessary? More detail on why/when to use this would be good.
* It's not 100% clear but I assume the full key must be used for the get() and getMany() calls? Just wondering if it's worth calling out that only the List interface supports retrieval by partial or range keys, particularly for getMany()?
* Probably just me, but reading about versionstamps made me think the data itself is versioned and I could retrieve previous versions of the data somehow. I understand now this isn't how it works, but others might get confused on this?

#### Deno.AtmoicCheck
* Atomic operation examples, including checks, would really help here. Possibly link to the runtime manual operations page?

#### Deno.KvListOptions
* cursors - not clear at all how these work. There's no examples in the runtime manual or elsewhere in the API docs I could find.
* reverse - with regards to ordering, it's probably worth highlighting more clearly what is being ordered (i.e. keys or values), though I think it's key order which can be reversed.
* batchSize - "Larger values will be clamped". This could be described with more accessible language? "Larger values will be ignored and a batch size of 500 will be used." or som such?

#### Deno.KvConsistencyLevel
* More description around consistency levels and the implications of them would be really useful here, especially with example scenarios. (Just seen there's a TODO for Consistency docs, so sounds like you will have this covered).
* Also, does consistenly level only apply to Deploy usage of KV? For a CLI use case, I can't see how consistency would come into play given you would only have a single instance of the DB on a single partition, etc.?

#### Deno.KvKeyPart
* It took me some time to get my head around the lexicographical ordering of key parts. Some examples would really help here with multi-part keys with different types within them perhaps?

#### Deno.KvListSelector
* Examples of this with multi-part keys, especially of different types, would be super useful

### Manual feedback

#### Operations page
* minor point, but for me, throughout the examples, having e.g. "sam" be both part of the key and the value is harder to parse. Something like this would work better for me:
`console.log(res1); // { key: ["users", "sam"], value: "sam's value", versionstamp: "00e0a2a0f0178b270000" }`
* For the sum, min and max mutations, include code in the example which shows the before and after affect of the mutation

#### Transactions
* minor typo: "To execute a transaction, one performs an atomic operations..."
* "Because OCC transactions are optimistic" - Took me awhile to find what this acronym meant. Probably worth adding "(OCC)" in the preceding paragraph which references the full name.
* Great example of an atomic transaction with the transferFunds demo, really pulled together a lot of parts I was not 100% getting

### General feedback
* More docs on best practices would be beneficial. Other databases use the concept of tables. Should you open a new KV DB per 'table' or take advantage of key prefixes?
* Best practice on data modelling and/or key choice considerations would be good
* Are there difference between using Deno.KV locally vs Deploy?
* I don't see that SQLite is the backing DB in Deno in the manual? Not sure how relevant that is, but might be worth adding. I've also seen folk asking about the possibility of swapping out the backing DB for self-hosted CLI instances. Again, not sure if that is worth documenting that you can't do this (and if it's on the radar).
* There's no mention of encryption at rest. Is this a feature?

### Deploy docs feedback
* I'm assuming Deploy doesn't support Deno.openKv('../path')? Worth documenting?
* More information around consistency would be helpful. E.g.
* Does strong consistency mean always reading and writing to the primary region?
* Discussion around what a primary region is, where it is and the role it plays
* Some visuals around strong vs eventual consistency with regards to the various regions at play would really help bring this to life
* I get the idea but don't fully understand the latency table. Does a 7ms eventual and strong consistency in North Virgina suggest this is the primary region? Same question for California, even though it is a higher latency, it's latency is the same for eventual and strong consistency, so I'm assuming it's also a primary region?
* Will there be suspension of inactive databases (if so, after what period) and if so what is the cold start time to bring them back online?

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.