mirror of https://gitee.com/bigwinds/arangodb
177 lines
4.2 KiB
Plaintext
177 lines
4.2 KiB
Plaintext
!CHAPTER The Users App
|
|
|
|
The users app provides a username-based user storage JavaScript API that can be used in other Foxx apps.
|
|
|
|
```js
|
|
var userStorage = Foxx.requireApp('/_users').userStorage;
|
|
```
|
|
|
|
!SECTION Exceptions
|
|
|
|
!SUBSECTION User Not Found
|
|
|
|
Indicates a user could not be found in the database.
|
|
|
|
`new userStorage.errors.UserNotFound(userId)`
|
|
|
|
Thrown by the user storage's *delete* and *get* methods if passed a user ID that does not exist in the database.
|
|
|
|
@EXAMPLES
|
|
|
|
```js
|
|
try {
|
|
userStorage.get(invalidUserId);
|
|
} catch(err) {
|
|
assertTrue(err instanceof userStorage.errors.UserNotFound);
|
|
}
|
|
```
|
|
|
|
!SUBSECTION Username Not Available
|
|
|
|
Indicates a username is already in use.
|
|
|
|
`new userStorage.errors.UsernameNotAvailable(username)`
|
|
|
|
Thrown by the user storage's *create* method if passed a *userData* object with a *username* that is already in use.
|
|
|
|
@EXAMPLES
|
|
|
|
```js
|
|
try {
|
|
userStorage.create({username: 'alreadyTaken'});
|
|
} catch(err) {
|
|
assertTrue(err instanceof userStorage.errors.UsernameNotAvailable);
|
|
}
|
|
```
|
|
|
|
!SECTION The user object
|
|
|
|
User objects are instances of a Foxx model with the following attributes:
|
|
|
|
* *userData*: application-specific user data. This is an arbitrary object that must at least have a *username* property set to the user's username.
|
|
* *authData*: an arbitrary object used by authentication apps to store sensitive data. For password authentication this could be a hash, for third-party authentication services this could be information about the user's identity. This attribute should never be exposed to the user directly.
|
|
|
|
!SECTION Create a user
|
|
|
|
Creates and saves a new instance of the user model.
|
|
|
|
`userStorage.create(userData)`
|
|
|
|
Throws *UsernameNotAvailable* if a user with the given username already exists.
|
|
|
|
*Parameter*
|
|
|
|
* *userData*: an arbitrary object that will be stored as the user's *userData* attribute when the model is saved to the database. This object must at least have a *username* property set to a string.
|
|
|
|
@EXAMPLES
|
|
|
|
```js
|
|
var user = userStorage.create({username: 'malaclypse'});
|
|
assertEqual(user.get('userData').username, 'malaclypse');
|
|
```
|
|
|
|
!SECTION Fetch an existing user
|
|
|
|
There are two ways to fetch a user via the user storage API:
|
|
|
|
* resolving a *username* with the user storage's *resolve* method
|
|
* calling the user storage's *get* method with a user ID directly
|
|
|
|
!SUBSECTION Resolve a *username*
|
|
|
|
Fetches a user with a given *username*.
|
|
|
|
`userStorage.resolve(username)`
|
|
|
|
If the username can not be resolved, a *UserNotFound* exception will be thrown instead.
|
|
|
|
*Parameter*
|
|
|
|
* *username*: an arbitrary string matching the username of the user you are trying to fetch.
|
|
|
|
@EXAMPLES
|
|
|
|
```js
|
|
var user = userStorage.resolve('malaclypse');
|
|
assertEqual(user.get('userData').username, 'malaclypse');
|
|
```
|
|
|
|
!SUBSECTION Resolve a user ID directly
|
|
|
|
Fetches a user with a given ID.
|
|
|
|
`userStorage.get(userId)`
|
|
|
|
Attempts to fetch the user with the given ID from the database. If the user does not exist, a *UserNotFound* exception will be thrown instead.
|
|
|
|
*Parameter*
|
|
|
|
* *userId*: a user *_key*.
|
|
|
|
@EXAMPLES
|
|
|
|
```js
|
|
var user = userStorage.get(userId);
|
|
assertEqual(user.get('_key'), userId);
|
|
```
|
|
|
|
!SECTION Delete a user
|
|
|
|
There are two ways to delete a user from the database:
|
|
|
|
* calling the user storage's *delete* method with a user ID directly
|
|
* telling a user to delete itself
|
|
|
|
!SUBSECTION Delete a user by its ID
|
|
|
|
Delete a user with a given ID.
|
|
|
|
`userStorage.delete(userId)`
|
|
|
|
Attempts to delete the user with the given user ID from the database. If the user does not exist, a *UserNotFound* exception will be thrown. The method always returns *null*.
|
|
|
|
*Parameter*
|
|
|
|
* *userId*: a user *_key*.
|
|
|
|
@EXAMPLES
|
|
|
|
```js
|
|
userStorage.delete(userId);
|
|
```
|
|
|
|
!SUBSECTION Tell a user to delete itself
|
|
|
|
Delete a user from the database.
|
|
|
|
`user.delete()`
|
|
|
|
Attempts to delete the user from the database.
|
|
|
|
Returns *true* if the user was deleted successfully.
|
|
|
|
Returns *false* if the user already didn't exist.
|
|
|
|
@EXAMPLES
|
|
|
|
```js
|
|
var user = userStorage.get(userId);
|
|
user.delete();
|
|
```
|
|
|
|
!SECTION Save a user
|
|
|
|
Save a user to the database.
|
|
|
|
`user.save()`
|
|
|
|
In order to commit changes made to the user in your code, you need to call this method.
|
|
|
|
@EXAMPLES
|
|
|
|
```js
|
|
var userData = user.get('userData');
|
|
userData.counter++;
|
|
user.save();
|
|
```
|