srap/src/database-backends/api.md

# runInTransaction

```js
runInTransaction(parentTX, (tx) => {
	// ... database operations go here ...
})
```

# lock

```js
lock(tx, {
	id,
	task
})
```

Returns: `true` if locking succeeded, `false` if the task was already locked

# unlock

```js
lock(tx, {
	id,
	task
})
```

# getItem

Fetch an item from the database by its unique named ID.

Wrapper API:

```js
getItem(tx, id)

getItem(tx, {
	id,
	optional = false
})
```

Expected backend API:

```js
getItem(tx, {
	id,
	optional
})
```

# createItem

Creates a new item or, if the item already exists, updates the existing item (if allowed). Tags/aliases are only ever added by this operation, never removed.

Wrapper API:

```js
createItem(tx, {
	id,
	tags = [],
	aliases = [],
	// Either `data` or `update` is required
	data,
	update, // callback(oldData)
	failIfExists = false,
	allowUpsert = true, // whether the *item object* is allowed to be updated, or should just be skipped if already exists
	parentID
})
```

Expected backend API:

```js
createItem(tx, {
	id,
	tags,
	aliases,
	update, // callback(oldData ?? {})
	failIfExists,
	allowUpsert,
	parentID
})
```

# renameItem

```js
let [ tx, { to, from }] = validateArguments(arguments, {
	tx: [ required, isTX ],
	options: [{
		to: [ required, isString ],
		from: [ required, isString ]
	}]
});
```

# repointAliases

```js
let [ tx, { to, from }] = validateArguments(arguments, {
	tx: [ required, isTX ],
	options: [{
		to: [ required, isString ],
		from: [ required, isString ]
	}]
});
```

# mergeItem

```js
let [ tx, { from, into, merge, mergeMetadata }] = validateArguments(arguments, {
	tx: [ required, isTX ],
	options: [{
		from: [ required, isString ],
		into: [ required, isString ],
		merge: [ required, isFunction ],
		mergeMetadata: [ defaultTo({}), anyProperty({
			key: [ required ],
			value: [ required, isFunction ]
		})],
	}]
});
```

# deleteItem

```js
let [ tx, { id }] = validateArguments(arguments, {
	tx: [ required, isTX ],
	options: [{
		id: [ required, isString ]
	}]
});
```

# createAlias

```js
let [ tx, { from, to, failIfExists }] = validateArguments(arguments, {
	tx: [ required, isTX ],
	options: [{
		from: [ required, isString ],
		to: [ required, isString ],
		failIfExists: [ defaultTo(false), isBoolean ] // TODO: Shouldn't this default to true, for any occurrence outside of a merge/rename?
	}]
});
```

# deleteAlias

```js
let [ tx, { from }] = validateArguments(arguments, {
	tx: [ required, isTX ],
	options: [{
		from: [ required, isString ]
	}]
});
```

# updateData

```js
let [ tx, { id, update }] = validateArguments(arguments, {
	tx: [ required, isTX ],
	options: [{
		id: [ required, isString ],
		update: [ required, isFunction ]
	}]
});
```

# updateMetadata

```js
let [ tx, { id, update, taskName, taskVersion, ttl }] = validateArguments(arguments, {
	tx: [ required, isTX ],
	options: [{
		id: [ required, isString ],
		update: [ required, isFunction ],
		taskName: [ required, isString ],
		taskVersion: [ required, isString ],
		ttl: [ isNumber ]
	}]
});
```

# expire

```js
let [ tx, { id, taskName }] = validateArguments(arguments, {
	tx: [ required, isTX ],
	options: [{
		id: [ required, isString ],
		taskName: [ required, isString ]
	}]
});
```

# setTTL

# allowFailure?

# log?

# countLockedTasks

Only a `tx` argument

# getUpdates

```js
let [ tx, { timestamp, prefix }] = validateArguments(arguments, {
	tx: [ required, isTX ],
	options: [ defaultTo({}), {
		timestamp: [ isDate ],
		prefix: [ isString ]
	}]
});
```