srap/src/database-backends/api.md

runInTransaction

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

lock

lock(tx, {
	id,
	task
})

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

unlock

lock(tx, {
	id,
	task
})

getItem

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

Wrapper API:

getItem(tx, id)

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

Expected backend API:

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:

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:

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

renameItem

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

repointAliases

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

mergeItem

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

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

createAlias

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

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

updateData

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

updateMetadata

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

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

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