Additional Permission and Role Helpers

[stnguyen90]

The Permission and Role helper classes are fine for creating new permissions from scratch, but they currently lack any way of parsing permissions retrieved from an existing collection or document.

Suppose there's a doc that has permissions for team:12345 to read and update. If I want to create another doc which copies the read permission from the first doc, but not the update permission, I seem to have no choice but to parse the permissions strings myself, looking for one that matches /^read\(/, and copy it directly as a string, which somewhat undermines the point of having helper classes to hide the implementation detail of those strings...

Previously this was easy, because read and write were separate parameters to createDocument, so I could just reflect back the read parameter. The new unified permissions are a step backwards in this regard.

Originally posted by @BenMemescape in #3612 (comment)

[safwanyp]

Seems like the previous way of creating a document was last done in 0.15.x. This looks nice and I get the importance behind this feature request.

I'm not quite sure how this feature can be implemented in the current permissions helper class.

One idea for the syntax could be something like this:

databases.createDocument(
   "[DATABASE_ID]", 
   "[COLLECTION_ID]", 
   "[DOCUMENT_ID]", 
   {},
   Permissions.copy(
      ["read", ...],    // <-- "read" | "update" | "create" | "delete" | "write"
      "[DOCUMENT_ID_TO_COPY_FROM]")
);

Would this be viable? It would add one more API call to fetch the document, and then parse the permissions into an array which would get returned by .copy

Edit: fixed syntax error, and added possible values in array

[BenMemescape]

@safwanyp I used copying permissions from one document to another as an example, but that's not the only reason we might want to be able to dissect permissions without having to resort to regex matching against them as strings. I think a copy() function would be less useful than, and not required if, we have helper functions that can answer questions like "which teams have update access to this document?" In most cases, that will be a document that we already have in a Document object because we're using as a template for another one. So the Permission class doesn't need to be given the power to fetch anything by ID, it literally just needs helpers that can be fed $permissions from some other object, parse it and return an array or something that can be (adjusted as required and) fed back into Permission.read() etc to create/update the other document. It could be as simple as Permissions.parse(permissionString) returning { "read": [ "team:1", "team:2" ], "update": [ "team:1" ], ... } (I can't remember if Permission.read() etc can take an array, hopefully they can...)

[stnguyen90]

Perhaps we can build something modeled after how we handle permissions and roles in the backend. So it would look like:

const permissions = document.$permissions.map((p) => Permission.parse(p));

const permission = permissions[0]; // permission is a Permission object

console.log(permission.permission); // would output read, create, update, or delete
console.log(permission.role); // would output any, guests, users, user, team, member, or label
console.log(permission.identifier); // would output the user id, team id, membership id, or label
console.log(permission.dimension); // would output verified (for something like users/verified), [ROLE] (for something like team:[TEAM_ID]/[ROLE])

// if the language allows, we could implement a toString or toJson method that coverts a Permission object to a string so that:

console.log(permission.toString()); // would output something like read("[PERMISSION_ROLE]")
console.log(permission.toJSON()); // would output something like read("[PERMISSION_ROLE]")

How's that?