Database adapters API

Errors#

Errors defined in the specification, such as AUTH_INVALID_USER_ID must be thrown as a LuciaError.

throw new LuciaError("AUTH_INVALID_USER_ID");

InitializeAdapter#

adapter configuration takes a InitializeAdapter function, which in turn returns the actual adapter instance. This function takes a LuciaError, and all errors thrown by the adapter must use this class instead of the one imported from lucia.

const customAdapter = (config: any) => {
	return (luciaError: typeof LuciaError) => ({
		// adapter
	});
};

lucia({
	adapter: customAdapter(options)
});

Adapter#

type Adapter = {
	getSessionAndUser?: (sessionId: string) => Promise<[SessionSchema, UserSchema] | [null, null]>;
} & UserAdapter &
	SessionAdapter;

getSessionAndUser()#

• An optional method of Adapter
• Must select session where session(id) equals parameter sessionId
• Must select user where user(id) equals session(id) of selected session
• Must return the session and user in a tuple if both exists, or null, null if not

const getSessionAndUser: (
	sessionId: string
) => Promise<[session: SessionSchema, user: UserSchema] | [session: null, user: null]>;

Parameters#

Returns#

UserAdapter#

type UserAdapter = Readonly<{
	getUser: (userId: string) => Promise<UserSchema | null>;
	setUser: (user: UserSchema, key: KeySchema | null) => Promise<void>;
	updateUser: (userId: string, partialUser: Partial<UserSchema>) => Promise<void>;
	deleteUser: (userId: string) => Promise<void>;

	getKey: (keyId: string) => Promise<KeySchema | null>;
	getKeysByUserId: (userId: string) => Promise<KeySchema[]>;
	setKey: (key: KeySchema) => Promise<void>;
	updateKey: (keyId: string, partialKey: Partial<KeySchema>) => Promise<void>;
	deleteKey: (keyId: string) => Promise<void>;
	deleteKeysByUserId: (userId: string) => Promise<void>;
}>;

deleteKey()#

• Must delete unique key where key(id) equals parameter keyId
• Must return void
• Parameter keyId may be invalid and must not throw errors if invalid
• Invalid keyId must be ignored and no errors should be thrown

const deleteKey: (keyId: string) => Promise<void>;

Parameters#

deleteKeysByUserId()#

• Must delete multiple key where key(user_id) equals parameter userId
• Must return void
• Parameter userId may be invalid and must not throw errors if invalid
• Invalid userId must be ignored and no errors should be thrown

const deleteKeysByUserId: (userId: string) => Promise<void>;

Parameters#

deleteUser()#

• Must delete unique user where user(id) equals parameter userId
• Must return void
• Parameter userId may be invalid and must not throw errors if invalid
• Invalid userId must be ignored and no errors should be thrown

const deleteUser: (userId: string) => Promise<void>;

Parameters#

getKey()#

• Must select unique key where key(id) equals parameter keyId
• Must return target key or null if there are no matches

const getKey: (keyId: string) => Promise<KeySchema | null>;

Parameters#

Returns#

getKeysByUserId()#

• Must select multiple key where key(user_id) equals parameter userId
• Must return an array of key or an empty array if there are no matches

const getKeysByUserId: (userId: string) => Promise<KeySchema[]>;

Parameters#

Returns#

getUser()#

• Must select unique user where user(id) equals parameter userId
• Must return target user or null if there are no matches

const getUser: (userId: string) => Promise<UserSchema | null>;

Parameters#

Returns#

setKey()#

• Must create new key
• Must throw error AUTH_DUPLICATE_KEY_ID if key(id) violates unique constraint
• May throw AUTH_INVALID_USER_ID if key(user_id) violates foreign key constraint

const setKey: (key: KeySchema) => Promise<void>;

Parameters#

setUser()#

• Must create new user
• Must create new key if parameter key is defined
• Must throw error AUTH_DUPLICATE_KEY_ID if key(id) violates unique constraint, if parameter key is defined
• key must not be created if user creation errors

const setUser: (user: UserSchema, key: KeySchema | null) => Promise<void>;

Parameters#

updateKey()#

• Must update fields, defined in parameter partialKey, of unique key where key(id) equals parameter keyId
• Must return void
• May throw error AUTH_INVALID_KEY_ID if target key does not exist

const updateKey: (keyId: string, partialKey: Partial<KeySchema>) => Promise<void>;

Parameters#

updateUser()#

• Must update fields, defined in parameter partialKey, of unique user where user(id) equals parameter userId
• Must return void
• May throw error AUTH_INVALID_USER_ID if target key does not exist

const updateUser: (userId: string, partialUser: Partial<UserSchema>) => Promise<void>;

Parameters#

SessionAdapter#

type SessionAdapter = Readonly<{
	getSession: (sessionId: string) => Promise<SessionSchema | null>;
	getSessionsByUserId: (userId: string) => Promise<SessionSchema[]>;
	setSession: (session: SessionSchema) => Promise<void>;
	updateSession: (sessionId: string, partialSession: Partial<SessionSchema>) => Promise<void>;
	deleteSession: (sessionId: string) => Promise<void>;
	deleteSessionsByUserId: (userId: string) => Promise<void>;
}>;

deleteSession()#

• Must delete unique session where session(id) equals parameter sessionId
• Returns void
• Parameter sessionId may be invalid and must not throw errors if invalid
• Invalid sessionId must be ignored and no errors should be thrown

const deleteSession: (sessionId: string) => Promise<void>;

Parameters#

deleteSessionsByUserId()#

• Must delete multiple session where session(user_id) equals parameter userId
• Must return void
• Parameter userId may be invalid and must not throw errors if invalid
• Invalid userId must be ignored and no errors should be thrown

const deleteSessionsByUserId: (userId: string) => Promise<void>;

Parameters#

getSession()#

• Must select unique session where session(id) equals parameter sessionId
• Must return target session or null if there are no matches

const getSession: (sessionId: string) => Promise<SessionSchema | null>;

Parameters#

Returns#

getSessionsByUserId()#

• Must select multiple session where session(user_id) equals parameter userId
• Must return an array of session or an empty array if there are no matches

const getSessionsByUserId: (userId: string) => Promise<SessionSchema[]>;

Parameters#

Returns#

setSession()#

• Must create new session
• May throw AUTH_INVALID_USER_ID if session(user_id) violates foreign key constraint

const setSession: (session: SessionSchema) => Promise<void>;

Parameters#

updateSession()#

• Must update fields, defined in parameter partialSession, of unique session where session(id) equals parameter keyId
• Must return void
• May throw error AUTH_INVALID_SESSION_ID if target session does not exist

const updateSession: (keyId: string, partialKey: Partial<SessionSchema>) => Promise<void>;

Parameters#