Documentation: Further define `thing` on db.create/merge/delete/select

[knackstedt]

Description

When writing code to interface with the database, the db client refers to thing as a table or record name throughout the operations. It's unclear what the format of this string should be, in case that there are special symbols that must be escaped or which symbols act as delimiters for the table name/record ID. I propose that there should be either a link to an explanation or an inline explanation for the format of this string to prevent developer confusion over the format of this field.

I encountered this by debugging an issue here where I had a record with a random string that would randomly fail to insert when the string generated with a dash.

As seen on the delete method (for example), it says table name or record ID, but it doesn't specify the format that the record ID needs to be in.

Notably, the thing property behaves differently with the create action, where it will insert records that do not get inserted on the merge action. This different behavior isn't mentioned or obvious, so it may cause problems if the format of thing isn't clear to the developer. Code: Surrealist:

Thanks :D

Is there an existing issue for this?

• [X] I have searched the existing issues

Code of Conduct

• [X] I agree to follow this project's Code of Conduct

[kearfy]

Hey @knackstedt! In the new v1.0.0-beta.x we have introduced a RecordId class. This means you can pass a string as a table to these methods, or a RecordId class representing... a RecordId. I still need to update the jsdoc blocks as they are a bit out of date, so I'll leave this issue open for the moment. Hope that helps!

[knackstedt]

Excellent! It's a bit foreign to me to use a RecordId class, but if it's well-documented then that's a non-issue. This definitely seems like a solid improvement :)