🚀 Feature: Pass parameters as an object

[dokgu]

🔖 Feature description

Pass the parameters as an object - something like:

type CreateMembershipProps = {
  teamId: string;
  roles: string[];
  email: string | undefined;
  userId: string | undefined;
  phone: string | undefined;
  url: string | undefined;
  ...
}

That way, developers can supply the parameters in any order and it wouldn't break anything and won't have to deal with parameter order gymnastics. I believe Appwrite is written in PHP but I'm sure something like this is also possible.

🎤 Pitch

I was upgrading my SDKs and I was looking at the breaking changes for createMembership() and it's fine that url is now optional but it's frustrating to keep having to check for the order of the parameters. For instance, on version 9.0.0, the order is

createMembership(teamId, roles, url, email, ...)

but on version 11.0.0 the order of parameters got switched all over:

createMembership(teamId, roles, email, userId, phone, url, ...)

Also, now I have to supply a bunch of undefined parameters just to get to the url towards the very end.

I didn't get any indication that something was wrong because Typescript just validates the types and email, userId, and url are all a bunch of string | undefined types so switching them around doesn't trigger any warnings from Typescript.

👀 Have you spent some time to check if this issue has been raised before?

• I checked and didn't find similar issue

🏢 Have you read the Code of Conduct?

• I have read the Code of Conduct

[stnguyen90]

@dokgu, thanks for raising this issue! 🙏🏼 I'm going to move this to the sdk-generator repo since it would apply to the sdk-for-web too.

[datner]

the suggested type

type CreateMembershipProps = {
 // ...
  email: string | undefined;
 // ...
}
createMembership({...}) // Type-Error, `email` is missing
createMembership({..., email: undefined }) // OK

should be

type CreateMembershipProps = {
 // ...
  email?: string
 // ...
}

createMembership({...}) // OK
createMembership({..., email: undefined }) // OK

The former demands a value, either a string or an explicit undefined, the latter does not. The latter gets auto-expanded to email?: string | undefined or stays email?: string with exactOptionalPropertyTypes set to true

[datner]

I'll attach my comment from the discord verbatim:

the experience using the js (node and web) api is quite painful, there are very obvious C# (and similar) influences in the api to the aggressive detriment of the user experince.. Consider this api:

db.createRelationshipAttribute(
  "<id>",
  "<id>",
  "<id>",
  RelationshipType.OneToMany,
  false,
  "",
  "",
  RelationMutate.Cascade,
)

you can't understand anything reading this, why is the api not the more standard Options interface

db.createRelationshipAttribute({
  databaseId: "<id>",
  parentCollectionId: "<id>",
  childCollectionId: "<id>",
  type: RelationshipType.OneToMany,
  required: false,
  // parentKey?: "",
  // childKey?: "",
  onDelete: RelationMutate.Cascade,
})

or creating namespaced clients

const Parent = new Collection(parentCollection) // <- Models.Collection
Parent.createRelationAttribute({
  to: "<id>",
  type: RelationshipType.OneToMany
})

or even follow the cross-reference style of collection.$id

const Parent = new Collection(parentCollection) // <- Models.Collection
const Child = new Collection(childCollection)
Parent.addRelation(Child, {
  type: RelationshipType.OneToMany
})

This is ofc before the lack of proper types and the recommendation of hard casting results.

I know Appwrite is massive, like MASSIVE massive, both internally and externally with the plethora of sdks, but I really wish the api was more ergonomic
The dream ofc would be to take inspiration from declarative schema-based apis like from kysely or drizzle instead of the imperative approach but I'm trying to keep things realistic