feat: Dart SDK update for version 20.0.0 #98
Conversation
WalkthroughThis PR makes widespread API and docs updates: fixes example type annotations from Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
lib/services/functions.dart (1)
322-338: Now I have enough information to provide a rewritten review comment. The verification reveals:
- ✅ TemplateReferenceType enum is properly defined and exported via
lib/enums.dart- ✅ Enum values are correct (branch, commit, tag) with proper serialization
- ✅ Tests are updated to use the new signature
- ❌ Breaking change is NOT documented in CHANGELOG.md - this is a critical gap
- ❌ No migration guidance provided for SDK consumers
Breaking API change in
createTemplateDeployment:versionparameter replaced withtype(TemplateReferenceType) andreference.While
TemplateReferenceTypeenum is properly exported inlib/enums.dart, this breaking change lacks documentation. TheCHANGELOG.mddoes not list this signature change under its breaking changes section (v14.0.0), and there is no migration guide provided for SDK consumers upgrading from previous versions.Add a CHANGELOG entry documenting the breaking change, and consider providing migration guidance in documentation or release notes for consumers of this method.
♻️ Duplicate comments (1)
docs/examples/sites/create.md (1)
13-14: LGTM! Consistent enum access pattern.The fully-qualified enum access is consistent with other examples and improves code clarity. The enum values have been flagged for verification in a related file.
Also applies to: 21-21
🧹 Nitpick comments (2)
test/services/storage_test.dart (1)
71-87: Bucket tests now exercisetransformations; consider asserting its valueIncluding
'transformations': truein the mocked responses for create/get/update bucket keeps these tests in sync with the updatedBucketmodel and storage API.If you want slightly stronger coverage, you could also assert
response.transformations == truein one of these tests to ensure the value is actually mapped through the model.Also applies to: 99-115, 126-142
lib/services/tables_db.dart (1)
1015-1017: UnconditionalkeyandtwoWayKeyin relationship column creation.These optional parameters are now always sent to the API. The
onDeletestill uses conditional inclusion withif (onDelete != null)and null-safe access, which is inconsistent with the other changes.Consider aligning
onDeletehandling with the other fields for consistency:final Map<String, dynamic> apiParams = { 'relatedTableId': relatedTableId, 'type': type.value, if (twoWay != null) 'twoWay': twoWay, 'key': key, 'twoWayKey': twoWayKey, - if (onDelete != null) 'onDelete': onDelete!.value, + 'onDelete': onDelete?.value, };
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (39)
docs/examples/avatars/get-browser.md(1 hunks)docs/examples/avatars/get-credit-card.md(1 hunks)docs/examples/avatars/get-favicon.md(1 hunks)docs/examples/avatars/get-flag.md(1 hunks)docs/examples/avatars/get-image.md(1 hunks)docs/examples/avatars/get-initials.md(1 hunks)docs/examples/avatars/get-qr.md(1 hunks)docs/examples/avatars/get-screenshot.md(2 hunks)docs/examples/functions/create-template-deployment.md(1 hunks)docs/examples/functions/create-vcs-deployment.md(1 hunks)docs/examples/functions/create.md(1 hunks)docs/examples/functions/get-deployment-download.md(1 hunks)docs/examples/functions/update.md(1 hunks)docs/examples/health/get-failed-jobs.md(1 hunks)docs/examples/sites/create-template-deployment.md(1 hunks)docs/examples/sites/create-vcs-deployment.md(1 hunks)docs/examples/sites/create.md(1 hunks)docs/examples/sites/get-deployment-download.md(1 hunks)docs/examples/sites/update.md(1 hunks)docs/examples/storage/create-bucket.md(1 hunks)docs/examples/storage/get-file-download.md(1 hunks)docs/examples/storage/get-file-preview.md(1 hunks)docs/examples/storage/get-file-view.md(1 hunks)docs/examples/storage/update-bucket.md(1 hunks)lib/enums.dart(1 hunks)lib/services/databases.dart(35 hunks)lib/services/functions.dart(5 hunks)lib/services/messaging.dart(38 hunks)lib/services/sites.dart(4 hunks)lib/services/storage.dart(5 hunks)lib/services/tables_db.dart(35 hunks)lib/services/users.dart(1 hunks)lib/src/enums/template_reference_type.dart(1 hunks)lib/src/enums/vcs_reference_type.dart(1 hunks)lib/src/models/bucket.dart(4 hunks)test/services/functions_test.dart(2 hunks)test/services/sites_test.dart(2 hunks)test/services/storage_test.dart(3 hunks)test/src/models/bucket_test.dart(2 hunks)
🔇 Additional comments (56)
docs/examples/health/get-failed-jobs.md (1)
10-13: Enum-qualified access pattern verified and correct.The change from
.v1DatabasetoName.v1Databaseis properly implemented:
Nameenum is correctly exported vialib/enums.dartand accessible to users importingdart_appwrite.dartget-failed-jobs.mdis the only health example using this enum; no consistency issues found across health examples- The qualified access pattern is the correct usage in this codebase
No further action needed.
docs/examples/storage/update-bucket.md (1)
20-23: LGTM! Documentation updated for enum qualification and new transformations parameter.The example now uses enum-qualified access (
Compression.none) and includes the newtransformationsparameter, both properly marked as optional.docs/examples/avatars/get-initials.md (1)
10-10: LGTM! Type name corrected to standard Dart convention.The type annotation has been correctly updated from
UInt8ListtoUint8List, matching Dart's core library type name.docs/examples/functions/get-deployment-download.md (1)
10-10: LGTM! Type name corrected.Correctly updated to
Uint8List, matching Dart's standard library type.docs/examples/storage/get-file-preview.md (1)
10-10: LGTM! Type name corrected.The type annotation has been updated to
Uint8List, matching Dart's core library convention.docs/examples/storage/get-file-view.md (1)
10-10: LGTM! Type name corrected.Updated to use the correct
Uint8Listtype name from Dart's core library.docs/examples/avatars/get-image.md (1)
10-10: LGTM! Type name corrected.Correctly updated to
Uint8List, consistent with all other documentation examples in this PR.docs/examples/sites/create-vcs-deployment.md (1)
12-12: Enum rename verified as complete throughout the codebase.All references to
VCSDeploymentTypehave been successfully replaced withVCSReferenceType. The enum is properly defined inlib/src/enums/vcs_reference_type.dartwith values forbranch,commit, andtag. It's correctly used in services (lib/services/sites.dart,lib/services/functions.dart), tests, and the documentation example. No lingering references to the old enum name remain.lib/services/users.dart (1)
38-39: Backend API v19.4.0 explicitly supports null value passing—no compatibility issue exists.The CHANGELOG.md for version 19.4.0 documents this exact change: "Fix passing of
nullvalues and stripping only non-nullable optional parameters from the request body." This confirms the unconditional inclusion ofphonewith explicitnullvalues is intentional and the backend API is designed to handle it correctly. The concern about backward compatibility is unfounded.docs/examples/sites/get-deployment-download.md (1)
10-14: Binary download example type looks correctThe example now uses a byte-list type for the deployment download result, which matches the expected binary response; no further changes needed here.
If you want to double‑check, confirm
Sites.getDeploymentDownloadcurrently returns a binary payload in the Dart SDK docs.lib/src/models/bucket.dart (1)
41-43: Buckettransformationsfield is wired consistently; check API compatibilityThe new
transformationsflag is added consistently across the model: field, constructor,fromMap, andtoMapare all in sync and will correctly round‑trip the value.Since
Bucket’s public constructor now requirestransformations, this is a minor breaking change for callers constructingBucketmanually and also assumes the backend always includestransformationsin responses. Please confirm this matches the 19.4.0 API contract and SDK versioning expectations.Also applies to: 57-58, 60-75, 79-95
docs/examples/avatars/get-qr.md (1)
10-15: QR avatar example type updated appropriatelyUsing a byte‑list type for the QR result aligns with returning raw image data; the snippet looks consistent with the rest of the SDK examples.
Optionally verify that
Avatars.getQRis documented as returning raw bytes so this example stays in sync.docs/examples/storage/get-file-download.md (1)
10-14: Storage file download example uses an appropriate byte typeThe example now models the download response as a byte buffer, which fits the storage download API behavior.
Please ensure all other storage download/view/preview examples are likewise using a byte type for consistency.
docs/examples/storage/create-bucket.md (1)
20-24: Create‑bucket example matches new enum andtransformationsflagQualifying
Compression.noneand surfacing the newtransformationsparameter in the example keeps it aligned with the updated storage API; the values used here are sensible defaults.Confirm that
Storage.createBucket’s signature in 19.4.0 includestransformationsand expects a bool so this example remains accurate.docs/examples/avatars/get-flag.md (1)
10-15: Flag avatar example result type is consistent with binary outputThe flag avatar example now uses a byte‑list type for the image data, consistent with other avatar and storage download examples.
As a quick sanity check, verify
Avatars.getFlagis still documented as returning raw bytes in the Dart SDK.docs/examples/functions/update.md (1)
13-29: Function update example uses namespaced runtime enum correctlySwitching to
Runtime.node145makes the example consistent with the enum‑qualified access pattern used elsewhere in the SDK docs.Please confirm the
Runtimeenum in the current Dart SDK still exposesnode145under that exact name.docs/examples/functions/create.md (1)
13-13: LGTM! Clearer enum access pattern.The change to fully-qualified enum access (
Runtime.node145) improves code clarity and makes the enum namespace explicit.docs/examples/avatars/get-browser.md (1)
10-10: LGTM! Correct type annotation.The typo fix from
UInt8ListtoUint8Listis correct—Uint8Listis the proper Dart type.docs/examples/avatars/get-credit-card.md (1)
10-10: LGTM! Correct type annotation.The typo fix from
UInt8ListtoUint8Listis correct.docs/examples/avatars/get-favicon.md (1)
10-10: LGTM! Correct type annotation.The typo fix from
UInt8ListtoUint8Listis correct.lib/enums.dart (1)
17-18: All verification checks passed successfully.The new enum part files (
template_reference_type.dartandvcs_reference_type.dart) exist at the expected location, the oldvcs_deployment_type.dartfile has been properly removed, and no dangling references toVCSDeploymentTyperemain in the codebase. The part directives at lines 17-18 inlib/enums.dartare correctly in place.docs/examples/functions/create-vcs-deployment.md (1)
12-12: All enum verification checks passed - the rename is complete and correct.The
VCSReferenceTypeenum is properly defined inlib/src/enums/vcs_reference_type.dartwith thebranchvalue included. No lingering references to the oldVCSDeploymentTypeexist in the codebase. The documentation example is consistent with the current SDK implementation.docs/examples/sites/create-template-deployment.md (1)
15-16: LGTM!The example correctly demonstrates the new
createTemplateDeploymentAPI signature usingTemplateReferenceType.branchwith thereferenceparameter, replacing the previousversionparameter.lib/src/enums/vcs_reference_type.dart (1)
3-13: LGTM!Clean enum definition with proper value mapping and JSON serialization. The rename from
VCSDeploymentTypetoVCSReferenceTypebetter reflects the enum's purpose.docs/examples/functions/create-template-deployment.md (1)
15-16: LGTM!The example correctly demonstrates the new
createTemplateDeploymentAPI for functions, usingTemplateReferenceType.committo show a different reference type option compared to the sites example.docs/examples/avatars/get-screenshot.md (2)
10-10: Type correction looks good.
Uint8Listis the correct Dart standard library type (fromdart:typed_data), fixing the previous typoUInt8List.
16-16: Enum usage improvements are correct.Using fully-qualified enum access (
Theme.light,Timezone.africaAbidjan,Output.jpg) instead of shorthand (.light, etc.) improves code clarity and is consistent with the updated SDK patterns.Also applies to: 20-20, 30-30
lib/services/messaging.dart (6)
55-55: Verify server handles nullscheduledAtin payload.The change from conditional to unconditional inclusion means
scheduledAt: nullwill now be sent in the request payload. Ensure the Appwrite server API correctly handles explicit null values for this field without side effects (e.g., clearing a previously set scheduled time unintentionally).
88-100: Unconditional field inclusion in PATCH may cause unintended field clearing.For
updateEmail, all optional fields are now included unconditionally (even when null). In PATCH semantics, this typically means "set these fields to null" rather than "leave unchanged". If users only want to updatesubject, they'll also sendnullfortopics,users,content, etc.Verify this aligns with the Appwrite server's expected behavior for partial updates.
142-142: Confirmdata: nullis acceptable for push notifications.The
datafield is now sent unconditionally. Ensure the server handlesdata: nullcorrectly without breaking push notification delivery.
212-212: Good use of null-safe operator for priority.Using
priority?.valuecorrectly handles the nullable enum, returningnullwhen the enum is not provided.
1508-1511: Same unconditional pattern inupdateTopic.Fields
nameandsubscribeare now included unconditionally in the PATCH request. This is consistent with the pattern applied throughout this file.
1-6: Summary: Unconditional parameter inclusion pattern applied consistently.This file systematically changes optional parameters from conditional (
if (x != null) 'key': x) to unconditional ('key': x) inclusion in API payloads. This appears to be an intentional API design change for SDK version 19.4.0. The pattern is applied consistently across all messaging endpoints.Verify this change aligns with Appwrite server API expectations, particularly for PATCH operations where null values may be interpreted as "clear field" rather than "no change".
test/src/models/bucket_test.dart (1)
20-20: LGTM!The test correctly covers the new
transformationsfield, following the established pattern for other boolean fields. The round-trip serialization test viatoMap/fromMapensures proper model behavior.Also applies to: 38-38
lib/src/enums/template_reference_type.dart (1)
1-13: LGTM!The enum follows Dart best practices with a const constructor, final value field, and
toJson()method for serialization. The values (branch, commit, tag) correctly represent Git reference types.test/services/functions_test.dart (2)
437-438: LGTM!The test correctly uses the new
TemplateReferenceType.commitenum andreferenceparameter, matching the updated API signature.
481-485: LGTM!The test correctly uses
VCSReferenceType.branchinstead of the previousVCSDeploymentType, aligning with the renamed enum.test/services/sites_test.dart (2)
443-444: LGTM!The test correctly uses
TemplateReferenceType.branchand the newreferenceparameter for template deployments.
487-491: LGTM!The test correctly uses the renamed
VCSReferenceType.branchenum for VCS deployments.lib/services/tables_db.dart (5)
253-253: Verify API contract for unconditionalpermissionsfield.The
permissionsfield is now included unconditionally increateTableandupdateTablepayloads, even when null. Ensure the API backend correctly handles null permissions (i.e., treats null as "no change" or "empty permissions" rather than an error).Also applies to: 300-300
1221-1222: Good use of null-safe access foronDelete.Using
onDelete?.valueinstead ofonDelete!.valueis the correct approach when the field is unconditionally included but may be null.
1379-1380: UnconditionalpermissionsandtransactionIdin row operations.Row CRUD methods now unconditionally include
permissionsandtransactionId. This enables cleaner payloads but requires the API to handle null values correctly.Also applies to: 1408-1408, 1437-1437, 1465-1465, 1491-1491
1639-1640: Unconditionalmin/maxin increment/decrement operations.The
minandmaxboundary fields are now always included. Ensure the API interprets null as "no boundary" rather than causing validation errors.Also applies to: 1671-1672
375-376: Based on my verification, I have gathered sufficient information to rewrite the review comment. Let me provide the final version:
Verify that the API correctly handles unconditional null values for
defaultandnewKeyfields.All column update methods now unconditionally include both
defaultandnewKeyfields in the payload, even when these nullable parameters are null. This differs from other service files (e.g.,databases.dart) which conditionally include nullable fields. Additionally, there's an inconsistency within create methods:defaultis included unconditionally whilearrayis conditionally included (only when not null). Confirm that the API backend is designed to handle null values for these fields without issues.lib/services/storage.dart (4)
38-39: Newtransformationsparameter looks good.The parameter is correctly added as optional (
bool?) and follows the same pattern as other boolean configuration flags likeantivirusandencryption.
45-45: Verify unconditional inclusion ofpermissionsis intentional.The
permissionsfield is now included unconditionally in the payload, which will sendnullto the API when not provided. Other optional fields likefileSecurityandenabledstill use conditional inclusion. Confirm this aligns with the backend API expectations.
94-95:updateBucketchanges are consistent withcreateBucket.The new
transformationsparameter and unconditionalpermissionshandling mirror thecreateBucketchanges, maintaining consistency.Also applies to: 101-101, 110-110
246-247:updateFilenow sendsnameandpermissionsunconditionally.Both fields will be included in the payload even when
null. Verify this matches the API specification—sendingnullfornameon an update endpoint may have unintended effects if the backend interprets it as "clear the name."lib/services/databases.dart (2)
269-269: Consistent pattern change across deprecatedDatabasesAPI.Multiple fields (
permissions,default,min,max,newKey,transactionId, etc.) are now included unconditionally in API payloads. Given these methods are all deprecated in favor ofTablesDB, this likely aligns with standardization efforts. Ensure the backend toleratesnullvalues for these fields.
1305-1306:updateRelationshipAttributeuses null-safe access foronDelete.Using
onDelete?.valuecorrectly handles the nullable enum, returningnullwhenonDeleteis not provided instead of throwing an error.lib/services/functions.dart (3)
355-358: Breaking API change:VCSDeploymentTyperenamed toVCSReferenceType.The enum type has been renamed from
VCSDeploymentTypetoVCSReferenceType. Existing code using the old type name will fail to compile.
503-503:scheduledAtnow included unconditionally.The field will be sent as
nullwhen not provided. Confirm the backend handles anullscheduledAtgracefully (e.g., treats it as "execute immediately" vs. a validation error).
624-625:updateVariablesendsvalueandsecretunconditionally.When
valueorsecretis not provided,nullwill be sent to the API. This could unintentionally clear an existing value or secret if the backend interpretsnullas "set to null" rather than "leave unchanged."lib/services/sites.dart (3)
309-327:createTemplateDeploymentchanges consistent with Functions service.The signature change from
versiontotype(TemplateReferenceType) andreferencemirrors the Functions service update, maintaining API consistency across services.
342-352:createVcsDeploymentuses renamedVCSReferenceTypeenum.Consistent with the Functions service change from
VCSDeploymentTypetoVCSReferenceType.
573-574:updateVariablesendsvalueandsecretunconditionally.Same pattern as Functions service. When not provided,
nullwill be sent. This could unintentionally clear existing values if the backend interpretsnullas "set to null."
| siteId: '<SITE_ID>', | ||
| name: '<NAME>', | ||
| framework: .analog, | ||
| framework: Framework.analog, |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Find the main SDK files and enum definitions
# First, let's see the repository structure
git ls-files | head -20
# Look for TypeScript/JavaScript enum definitions
fd -e ts -e js -e tsx -e jsx | grep -v node_modules | head -30Repository: appwrite/sdk-for-dart
Length of output: 776
🏁 Script executed:
#!/bin/bash
# Find Dart files with enum definitions
fd -e dart | grep -v pubspec | head -30
# Look for enum definitions in Dart files
rg -n "enum Framework\|enum BuildRuntime\|enum Adapter" --type dartRepository: appwrite/sdk-for-dart
Length of output: 750
🏁 Script executed:
#!/bin/bash
# Check the size of enums.dart
wc -l lib/enums.dart
# Read the entire file to find the enums
cat -n lib/enums.dartRepository: appwrite/sdk-for-dart
Length of output: 1851
🏁 Script executed:
#!/bin/bash
# Read the three enum files
echo "=== framework.dart ==="
cat -n lib/src/enums/framework.dart
echo -e "\n=== build_runtime.dart ==="
cat -n lib/src/enums/build_runtime.dart
echo -e "\n=== adapter.dart ==="
cat -n lib/src/enums/adapter.dartRepository: appwrite/sdk-for-dart
Length of output: 3918
🏁 Script executed:
#!/bin/bash
# Read the update.md file to see the actual enum usage
cat -n docs/examples/sites/update.mdRepository: appwrite/sdk-for-dart
Length of output: 1418
The enum value Adapter.static does not exist; it should be Adapter.xstatic.
The verification found that Framework.analog and BuildRuntime.node145 are valid enum values in the SDK. However, Adapter.static is incorrect. The actual enum member in lib/src/enums/adapter.dart (line 4) is named Adapter.xstatic, which has the string value 'static'. The documentation file at line 21 must be updated to use Adapter.xstatic instead of Adapter.static.
🤖 Prompt for AI Agents
In docs/examples/sites/update.md around line 13, the code uses a non-existent
enum member Adapter.static; replace it with the correct enum member
Adapter.xstatic (the enum is defined in lib/src/enums/adapter.dart and xstatic
has the string value 'static') so the example compiles and matches the SDK enum
names.
ChiragAgg5k
changed the title
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
CHANGELOG.md(1 hunks)README.md(1 hunks)docs/examples/avatars/get-screenshot.md(1 hunks)lib/services/account.dart(4 hunks)lib/src/client_browser.dart(1 hunks)lib/src/client_io.dart(1 hunks)pubspec.yaml(1 hunks)
✅ Files skipped from review due to trivial changes (2)
- lib/src/client_browser.dart
- pubspec.yaml
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/examples/avatars/get-screenshot.md
🔇 Additional comments (3)
README.md (1)
26-26: LGTM! Version dependency correctly updated.The package version bump from ^19.4.0 to ^20.0.0 aligns with the PR objectives and SDK release.
lib/src/client_io.dart (1)
45-47: LGTM! SDK version metadata correctly updated.The HTTP header version strings have been properly updated to reflect the 20.0.0 release.
lib/services/account.dart (1)
303-303: Verify backend API alignment for endpoint path change.The MFA challenge endpoint path has been updated from
/account/mfa/challenge(singular) to/account/mfa/challenges(plural) across all four MFA challenge methods (lines 303, 324, 349, 373). This is a breaking change that will cause 404 errors if the backend API hasn't been updated correspondingly.Please confirm:
- The backend API version 20.0.0 has deployed this endpoint path change
- Any migration guide or changelog documents this breaking change for users upgrading from previous SDK versions
|
|
||
| * Rename `VCSDeploymentType` enum to `VCSReferenceType` | ||
| * Change `createTemplateDeployment` method signature: replace `version` parameter with `type` (TemplateReferenceType) and `reference` parameters | ||
| * Add `Theme`, `Timezone` and `Output` enums |
There was a problem hiding this comment.
Remove duplicate enum entries.
Line 7 claims to add Theme, Timezone, and Output enums in version 20.0.0, but Line 12 already documents these same enums as added in version 19.4.0. Enums cannot be added in two different versions.
Please verify which version actually introduced these enums and remove the duplicate entry.
🤖 Prompt for AI Agents
CHANGELOG.md around lines 7 to 12: the entry on line 7 ("Add `Theme`, `Timezone`
and `Output` enums" in version 20.0.0) duplicates the same enums already
documented as added in version 19.4.0 on line 12; determine which release
actually introduced these enums (verify git history or commit that added the
enums) and remove the incorrect duplicate entry so the enums are only documented
once under the correct version.
This PR contains updates to the Dart SDK for version 20.0.0.
Summary by CodeRabbit
Release Notes
New Features
transformationsparameter to bucket creation and update operationsBug Fixes
Documentation
Chores
✏️ Tip: You can customize this high-level summary in your review settings.