DOCSP-29928 Serialization for Dart #3235

lindseymoore · 2024-04-26T23:44:48Z

Pull Request Info

Jira ticket: https://jira.mongodb.org/browse/DOCSP-29928

Serialization: New page documenting serialization

Reminder Checklist

Before merging your PR, make sure to check a few things.

Did you tag pages appropriately?
- genre
- meta.keywords
- meta.description
Describe your PR's changes in the Release Notes section
Create a Jira ticket for related docs-app-services work, if any

Release Notes

Flutter SDK

Serialization: Add new page for serialization of objects to and from EJSON.

Review Guidelines

REVIEWING.md

github-actions · 2024-04-26T23:46:10Z

Readability for Commit Hash: d7de333

You can see any previous Readability scores (if they exist) by looking
at the comment's history.

Readability scores for changed documents:

source/sdk/flutter/realm-database: Grade Level: 27.0, Reading Ease: -76.58
source/sdk/flutter/realm-database/serialization: Grade Level: 11.4, Reading Ease: 34.12

For Grade Level, aim for 8 or below.

For Reading Ease scores, aim for 60 or above:

Score	Difficulty
90-100	Very Easy
80-89	Easy
70-79	Fairly Easy
60-69	Medium
50-59	Fairly Hard
30-49	Hard
0-29	Very Hard

For help improving readability, try Hemingway App.

nielsenko

I have added a few comments.

I also noticed that the syntax highlighting is missing a few places.

My biggest question is; if we want to show how to serialize non-realm objects? I guess we can wait with that until later, perhaps when the new mongo db client (or what it ends up being named lands).

examples/dart/test/serialization_test.dart

source/sdk/flutter/realm-database/serialization.txt

lindseymoore · 2024-05-21T21:32:21Z

Thanks @nielsenko! Let me know if there is anything else. Will look into why the syntax highlighting is off.

For serializing non-realm objects, I linked to this page on BSON Data Types and Representation in the "Supported Data Types" section of the page.

Edit: Unfortunately, we don't have control over whether the syntax highlighting registers or not.

cbullinger

Back to you with some questions and comments. And let's clean up and refactor the tests for idempotency

examples/dart/test/serialization_test.dart

source/sdk/flutter/realm-database/serialization.txt

cbullinger

Some suggestions but overall I think this looks good

source/examples/generated/flutter/serialization_test.snippet.serialize.dart

source/sdk/flutter/realm-database/serialization.txt

examples/dart/test/serialization_test.dart

nielsenko

LGTM. I have a few suggestions, but feel free to disregard them if you don't agree.

nielsenko · 2024-06-06T08:52:57Z

source/sdk/flutter/realm-database/serialization.txt

+- Array
+- Binary
+- Boolean
+- Date
+- Document
+- Decimal128
+- Double
+- Int32
+- Int64
+- MaxKey
+- MinKey
+- ObjectID
+- String
+- Symbol
+- Null
+- Undefined


Consider annotating each entry with the associated dart type perhaps, ie. Array (List), Binary (Uint8List), Document (Map<String, dynamic>), etc.

Agreed. Can we make this a table, @lindseymoore? Alternately, we could make it a table of:
Dart/Realm type | Serialized type | Example output

nielsenko · 2024-06-06T08:56:32Z

source/sdk/flutter/realm-database/serialization.txt

+- Undefined
+
+For more information and examples on the serialization for each of these types,
+see :manual:`BSON Data Types and Associated Representations </reference/mongodb-extended-json/#bson-data-types-and-associated-representations>`.


Following this link, and then the link to the full spec, I noticed it is redirecting us to https://github.com/mongodb/specifications/blob/master/source/extended-json.md. Completely unrelated to this PR, but perhaps worth looking into.

examples/dart/test/serialization_test.dart

cbullinger

Formatting and content suggestions. We also need to make sure the other affected Flutter pages are updated with this new method (e.g. Call an Atlas Function)

source/sdk/flutter/realm-database/serialization.txt

cbullinger · 2024-06-26T13:15:44Z

source/sdk/flutter/realm-database/serialization.txt

+
+The Atlas Device SDK for Flutter supports serialization and deserialization of
+:manual:`Extended JSON (ESJON) </reference/mongodb-extended-json>` to and from static Realm objects.
+Serialization allows for easier integration with MongoDB APIs.


Suggested change

Serialization allows for easier integration with MongoDB APIs.

The Flutter SDK can use this full-document EJSON encoding to communicate

directly with MongoDB Atlas, such as through the following APIs:

- App Services :ref:`Function calls <flutter-call-function>`

- Credentials with :ref:`custom function authentication <flutter-login-custom-function>`

- User profile and :ref:`custom user data <flutter-custom-user-data>`

You'll also need to check these linked pages and make sure there aren't any doc impacts (e.g. the Call a Function page instructions need to be updated with this new ESJON method)

fyi - this list will eventually include the enhanced Query MongoDB functionality, which hasn't been released yet

Ticket for this work: https://jira.mongodb.org/browse/DOCSP-41296

I think the suggested edits here are still valid, even if the linked pages will be updated in separate tickets (let's make sure we have tickets tracking the custom function auth updates too. doesn't look like custom user data has any impacts)

I see the function on this page converts to json rather than ejson. Is converting to ejson the more updated way; will it no longer work with json?
I'll add the function auth update to the previous ticket!

ooh, good catch! 🕵️ looks like that call uses jsonEncode() and jsonDecode() internally, so we should probably still point users to serialize object args that way. Although now I'm a little confused by the last sentence... ("The Function returns a dynamic value containing MongoDB Extended JSON (EJSON) deserialized to a native Dart object.")

Either way, I think we're good to leave this as-is. Thanks for digging into this and confirming!

netlify · 2024-07-02T22:14:07Z

❌ Deploy Preview for device-sdk failed. Why did it fail? →

Name	Link
🔨 Latest commit	`d7de333`
🔍 Latest deploy log	https://app.netlify.com/sites/device-sdk/deploys/669aafd947b42300085d1631

source/sdk/flutter/realm-database/serialization.txt

examples/dart/test/person.dart

cbullinger · 2024-07-09T20:30:57Z

examples/dart/test/serialization_test.dart

+  // Null
+  int? a;
+
+  // RealmValue supported??? Engineer said so but doesn't seem to be so


Can we update these comments to be more descriptive of the issue (to help anyone else reading them who might not have the context)?

Do we have a ticket or something to track this work, so we can update once engineering get the bug fixes in? @krollins-mdb do we have a standard for handling feature docs with known bugs? i.e. do we need to note anything in the docs?

Added the engineering ticket to a comment (RDART-1063). I can make a DOCSP ticket to update this section with RealmValue and Decimal128 once engineering ticket is resolved. Doesn't seem to be high priority for engineering, so I'm comfortable listing RealmValue and Decimal128 as unsupported for now. Will let engineering know if that sounds good!
DOCSP ticket: https://jira.mongodb.org/browse/DOCSP-41612

examples/dart/test/serialization_test.dart

cbullinger · 2024-07-09T20:37:00Z

source/sdk/flutter/realm-database/serialization.txt

+
+The Atlas Device SDK for Flutter supports serialization and deserialization of
+:manual:`Extended JSON (ESJON) </reference/mongodb-extended-json>` to and from static Realm objects.
+Serialization allows for easier integration with MongoDB APIs.


I think the suggested edits here are still valid, even if the linked pages will be updated in separate tickets (let's make sure we have tickets tracking the custom function auth updates too. doesn't look like custom user data has any impacts)

source/sdk/flutter/realm-database/serialization.txt

cbullinger

🚀 You did it! Page looks great, @lindseymoore! ❤️

source/sdk/flutter/realm-database/serialization.txt

docs-builder-bot · 2024-07-19T19:11:55Z

✨ Staging URL: https://preview-mongodbmongodb.gatsbyjs.io/realm/master/

🪵 Logs

job log: 674381df1e945ee314721abec17bb0a7c8ca4f09

lindseymoore added 2 commits April 26, 2024 19:36

DOCSP-29928 Serialization for Dart

d4e9b3e

check staging for TOC

bbce292

lindseymoore added 4 commits April 26, 2024 20:49

page clean up

f37f337

fix code copy

9478fcb

clean code file

77e252d

Remove full document encoding section

3c55110

nielsenko reviewed May 21, 2024

View reviewed changes

examples/dart/test/serialization_test.dart Outdated Show resolved Hide resolved

source/sdk/flutter/realm-database/serialization.txt Outdated Show resolved Hide resolved

source/sdk/flutter/realm-database/serialization.txt Outdated Show resolved Hide resolved

lindseymoore added 3 commits May 21, 2024 17:35

tech review comments

1010281

add unsupported types

3f421bf

meta

3724156

cbullinger requested changes May 22, 2024

View reviewed changes

lindseymoore added 8 commits May 23, 2024 19:03

review comments pt1

8ed823e

more review comments: add io-code block

d0a81a8

ejson annotation, custom encoder, fix io code block

cd8b03c

typo

115406d

fix include

cfba0ef

typos

6c39e58

clean up realm and import object model

04f3eb5

detail

3f1856b

cbullinger approved these changes Jun 4, 2024

View reviewed changes

lindseymoore added 2 commits June 5, 2024 17:44

fix test clean up and bluehawk

02fba64

wording

7e5d73d

nielsenko reviewed Jun 6, 2024

View reviewed changes

lindseymoore added 5 commits June 6, 2024 15:42

add typed example for deserialize

00542ef

start making object model with different ypes

d47fa6c

table

9025288

remaining changes

3354a43

fix formatting

519f742

lindseymoore added 7 commits June 13, 2024 12:06

testing

1418070

fix table

2e9f277

fixing formatting

08c1de0

remove RealmValue and Decimal 128

e9bf824

table

8446218

table?

a0edb44

fix table text

e3974fd

cbullinger requested changes Jun 26, 2024

View reviewed changes

review comments pt 1

29f14e9

lindseymoore added 3 commits July 3, 2024 22:57

table formatting

b832398

fix table format

bbdc7d4

imporve table and wording

26d20be

dacharyc added the Add to consolidation feature branch PR merged after cutting the consolidation feature branch, so cherry-pick to the feature branch. label Jul 9, 2024

cbullinger requested changes Jul 9, 2024

View reviewed changes

lindseymoore added 4 commits July 18, 2024 16:14

review comments

407f639

line highlight

7cc73b5

add list of supported apis

d090f0a

spacing

c553519

cbullinger approved these changes Jul 18, 2024

View reviewed changes

source/sdk/flutter/realm-database/serialization.txt Outdated Show resolved Hide resolved

source/sdk/flutter/realm-database/serialization.txt Outdated Show resolved Hide resolved

lindseymoore added 2 commits July 19, 2024 13:57

review comments

12c031b

formatting

d7de333

lindseymoore merged commit 674381d into mongodb:master Jul 19, 2024
7 of 11 checks passed

dacharyc removed the Add to consolidation feature branch PR merged after cutting the consolidation feature branch, so cherry-pick to the feature branch. label Jul 19, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOCSP-29928 Serialization for Dart #3235

DOCSP-29928 Serialization for Dart #3235

lindseymoore commented Apr 26, 2024 •

edited

Loading

github-actions bot commented Apr 26, 2024 •

edited

Loading

nielsenko left a comment

lindseymoore commented May 21, 2024 •

edited

Loading

cbullinger left a comment

cbullinger left a comment

nielsenko left a comment

nielsenko Jun 6, 2024 •

edited

Loading

cbullinger Jun 6, 2024

nielsenko Jun 6, 2024

cbullinger left a comment

cbullinger Jun 26, 2024

lindseymoore Jul 9, 2024

cbullinger Jul 9, 2024

lindseymoore Jul 18, 2024

cbullinger Jul 18, 2024

netlify bot commented Jul 2, 2024 •

edited

Loading

cbullinger Jul 9, 2024

lindseymoore Jul 18, 2024 •

edited

Loading

cbullinger Jul 9, 2024

cbullinger left a comment

docs-builder-bot commented Jul 19, 2024

-Serialization allows for easier integration with MongoDB APIs.
+The Flutter SDK can use this full-document EJSON encoding to communicate
+directly with MongoDB Atlas, such as through the following APIs:
+- App Services :ref:`Function calls <flutter-call-function>`
+- Credentials with :ref:`custom function authentication <flutter-login-custom-function>`
+- User profile and :ref:`custom user data <flutter-custom-user-data>`

DOCSP-29928 Serialization for Dart #3235

DOCSP-29928 Serialization for Dart #3235

Conversation

lindseymoore commented Apr 26, 2024 • edited Loading

Pull Request Info

Reminder Checklist

Release Notes

Review Guidelines

github-actions bot commented Apr 26, 2024 • edited Loading

nielsenko left a comment

Choose a reason for hiding this comment

lindseymoore commented May 21, 2024 • edited Loading

cbullinger left a comment

Choose a reason for hiding this comment

cbullinger left a comment

Choose a reason for hiding this comment

nielsenko left a comment

Choose a reason for hiding this comment

nielsenko Jun 6, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cbullinger left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

netlify bot commented Jul 2, 2024 • edited Loading

❌ Deploy Preview for device-sdk failed. Why did it fail? →

Choose a reason for hiding this comment

lindseymoore Jul 18, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cbullinger left a comment

Choose a reason for hiding this comment

docs-builder-bot commented Jul 19, 2024

🪵 Logs

lindseymoore commented Apr 26, 2024 •

edited

Loading

github-actions bot commented Apr 26, 2024 •

edited

Loading

lindseymoore commented May 21, 2024 •

edited

Loading

nielsenko Jun 6, 2024 •

edited

Loading

netlify bot commented Jul 2, 2024 •

edited

Loading

lindseymoore Jul 18, 2024 •

edited

Loading