Skip to content

Add detail for ingestSnapshot docs - #493

Closed
curran wants to merge 1 commit into
share:masterfrom
curran:patch-14
Closed

curran wants to merge 1 commit into
share:masterfrom
curran:patch-14

Conversation

@curran

@curran curran commented Jul 10, 2021

Copy link
Copy Markdown
Contributor

Greetings,

I was attempting to use ingestSnapshot by generating the snapshot on the server and sending it to the client, and I realized that the best documentation for how to create that actual snapshot object were found in the comments thread of this issue: #254

I tried to find in the codebase where the snapshot object is constructed by looking into the doc.fetch internals, but could not find it. So I figured I would contribute this small documentation change.

@coveralls

Copy link
Copy Markdown

Coverage Status

Coverage remained the same at 97.401% when pulling 61e198a on curran:patch-14 into 851f38a on share:master.

@alecgibson alecgibson left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm curious; what's the use-case here? Should we add a utility method to Doc?

Comment thread docs/api/doc.md

{: .warn }
This method is generally called internally as a result of [`fetch()`](#fetch) or [`subscribe()`](#subscribe), and not directly from consumer code. Consumers *may* want to use this method to ingest data that was transferred to the client externally to the client's ShareDB connection.
This method is generally called internally as a result of [`fetch()`](#fetch) or [`subscribe()`](#subscribe), and not directly from consumer code. Consumers *may* want to use this method to ingest data that was transferred to the client externally to the client's ShareDB connection. To generate a snapshot from a fetched `Doc`, you can do the following: `const snapshot = { v: doc.version, data: doc.data, type: doc.type }`.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this isn't quite correct:

  • doc.type is an object
  • snapshot.type is a string (doc.type.uri)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The other thing you could do is just cross-link to the Snapshot docs

@curran

curran commented Jul 22, 2021 •

Copy link
Copy Markdown
Contributor Author

@alecgibson Thanks for reviewing!

I'm curious; what's the use-case here?

The use case:

  • Server-side code runs a ShareDB fetch operation.
  • That data gets baked into the server-rendered HTML.
  • That data gets parsed in the client and passed into ingestSnapshot
  • so that the data is not fetched again during a subscribe.

In general, the need is to derive a well formed snapshot from an already fetched Doc (on the server), so that it can be passed into ingestSnapshot (on the client). For a given page load, this would reduce the number of database queries for the same document from 2 (server side fetch, client side subscribe without ingestSnapshot) to 1.

It's also expressed in the existing comment: "... ingest data that was transferred to the client externally to the client's ShareDB connection."

Should we add a utility method to Doc?

Yes please! That would be amazing. This would have the added benefit of being covered by tests, which would be really nice.

@curran

curran commented Jul 22, 2021

Copy link
Copy Markdown
Contributor Author

Oh hey! I have some public code I can reference as a concrete use case:

This is all very WIP so bear with me. I hope what I'm trying to do makes sense. Thanks!

@curran

curran commented Aug 22, 2021

Copy link
Copy Markdown
Contributor Author

Closing in favor of #508.

@curran curran closed this Aug 22, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants