Skip to content

DirectoryService

katanakit-js / DirectoryService

Defined in: core/services/directory.service.ts:211

User management over any storage, with the lockout guards built in.

Pure orchestration: every method either returns a DirectoryResult or hands the decision back to the repository. No exceptions for expected refusals — “you may not do that” is an answer, not a crash, and a caller should not have to distinguish the two in a catch.

Deliberately not here: deleting a provider account, revoking a live session, forcing a password change. Those belong to the identity provider and are the caller’s to invoke — a directory row disappearing must not be the only thing that happened.

const directory = new DirectoryService({ repository });
const suspended = await directory.useSuspend(actor, 42, "left the company");
if (!suspended.ok && suspended.error.code === "last_owner") {
// render the "promote someone else first" message
}
new DirectoryService(__namedParameters): DirectoryService;

Defined in: core/services/directory.service.ts:214

Parameter Type
__namedParameters DirectoryServiceOptions

DirectoryService

useAddRole(
actor,
id,
role
): Promise<DirectoryResult<{
displayName?: string;
email?: string;
id: string | number;
metadata?: Record<string, unknown>;
principalSubject?: string;
roles: string[];
scope?: string;
status: "active" | "pending" | "suspended" | "deactivated";
}>>;

Defined in: core/services/directory.service.ts:282

Grants a role. Refuses when the actor does not already hold it.

Parameter Type
actor DirectoryActor
id string | number
role string

Promise<DirectoryResult<{ displayName?: string; email?: string; id: string | number; metadata?: Record<string, unknown>; principalSubject?: string; roles: string[]; scope?: string; status: "active" | "pending" | "suspended" | "deactivated"; }>>


useCreate(actor, user): Promise<DirectoryResult<{
displayName?: string;
email?: string;
id: string | number;
metadata?: Record<string, unknown>;
principalSubject?: string;
roles: string[];
scope?: string;
status: "active" | "pending" | "suspended" | "deactivated";
}>>;

Defined in: core/services/directory.service.ts:239

Registers a person.

The actor is required even though creating is usually permissive: it is what lets a deployment decide later that creation is itself a capability, without changing this signature.

Parameter Type
actor DirectoryActor
user Omit<DirectoryUser, "id">

Promise<DirectoryResult<{ displayName?: string; email?: string; id: string | number; metadata?: Record<string, unknown>; principalSubject?: string; roles: string[]; scope?: string; status: "active" | "pending" | "suspended" | "deactivated"; }>>


useDelete(actor, id): Promise<DirectoryResult<true>>;

Defined in: core/services/directory.service.ts:397

Removes the record permanently.

Separate from useSuspend on purpose — and it does not touch the provider account, so a caller who needs real revocation must do that too.

Parameter Type
actor DirectoryActor
id string | number

Promise<DirectoryResult<true>>


useGet(id): Promise<DirectoryResult<{
displayName?: string;
email?: string;
id: string | number;
metadata?: Record<string, unknown>;
principalSubject?: string;
roles: string[];
scope?: string;
status: "active" | "pending" | "suspended" | "deactivated";
}>>;

Defined in: core/services/directory.service.ts:228

Fetches one user.

Parameter Type
id string | number

Promise<DirectoryResult<{ displayName?: string; email?: string; id: string | number; metadata?: Record<string, unknown>; principalSubject?: string; roles: string[]; scope?: string; status: "active" | "pending" | "suspended" | "deactivated"; }>>


useList(query?): Promise<DirectoryPageResult>;

Defined in: core/services/directory.service.ts:219

Lists users, filtered and paginated by the repository.

Parameter Type
query? Partial<DirectoryQuery>

Promise<DirectoryPageResult>


useReactivate(actor, id): Promise<DirectoryResult<{
displayName?: string;
email?: string;
id: string | number;
metadata?: Record<string, unknown>;
principalSubject?: string;
roles: string[];
scope?: string;
status: "active" | "pending" | "suspended" | "deactivated";
}>>;

Defined in: core/services/directory.service.ts:372

Returns a suspended account to service.

Parameter Type
actor DirectoryActor
id string | number

Promise<DirectoryResult<{ displayName?: string; email?: string; id: string | number; metadata?: Record<string, unknown>; principalSubject?: string; roles: string[]; scope?: string; status: "active" | "pending" | "suspended" | "deactivated"; }>>


useRemoveRole(
actor,
id,
role
): Promise<DirectoryResult<{
displayName?: string;
email?: string;
id: string | number;
metadata?: Record<string, unknown>;
principalSubject?: string;
roles: string[];
scope?: string;
status: "active" | "pending" | "suspended" | "deactivated";
}>>;

Defined in: core/services/directory.service.ts:312

Revokes a role, keeping the person active.

Parameter Type
actor DirectoryActor
id string | number
role string

Promise<DirectoryResult<{ displayName?: string; email?: string; id: string | number; metadata?: Record<string, unknown>; principalSubject?: string; roles: string[]; scope?: string; status: "active" | "pending" | "suspended" | "deactivated"; }>>


useSuspend(
actor,
id,
reason?
): Promise<DirectoryResult<{
displayName?: string;
email?: string;
id: string | number;
metadata?: Record<string, unknown>;
principalSubject?: string;
roles: string[];
scope?: string;
status: "active" | "pending" | "suspended" | "deactivated";
}>>;

Defined in: core/services/directory.service.ts:340

Suspends access while keeping the record and its audit trail.

This is the operation a real offboarding uses, and it is not useDelete. Removing the row loses the evidence that the account existed; leaving the account merely “inactive” in a provider that has no such state means someone can still sign in. Suspension is the reversible, auditable middle ground, and useDelete is reserved for a genuine correction.

Parameter Type
actor DirectoryActor
id string | number
reason? string

Promise<DirectoryResult<{ displayName?: string; email?: string; id: string | number; metadata?: Record<string, unknown>; principalSubject?: string; roles: string[]; scope?: string; status: "active" | "pending" | "suspended" | "deactivated"; }>>


useUpdate(
actor,
id,
patch
): Promise<DirectoryResult<{
displayName?: string;
email?: string;
id: string | number;
metadata?: Record<string, unknown>;
principalSubject?: string;
roles: string[];
scope?: string;
status: "active" | "pending" | "suspended" | "deactivated";
}>>;

Defined in: core/services/directory.service.ts:258

Patches a user’s fields.

Roles go through the demotion guards even here, because an update that silently accepts { roles: [] } is a way around useRemoveRole entirely.

Parameter Type
actor DirectoryActor
id string | number
patch Partial<Omit<DirectoryUser, "id">>

Promise<DirectoryResult<{ displayName?: string; email?: string; id: string | number; metadata?: Record<string, unknown>; principalSubject?: string; roles: string[]; scope?: string; status: "active" | "pending" | "suspended" | "deactivated"; }>>