User List

Get a paginated list of all users in the system. This is useful for user management, directory services, and permission assignment.

Definition

db(databaseName: string)
  .userList(offset?: number): Promise<Result<TUserFindResponse>>;

Where TUserFindResponse is defined as:

type TUserFindResponse = TPaginationReturn<TUserMeResponse[]>;

type TPaginationReturn<T> = {
  data: T;
  total: number;
  offset: number;
};

type TUserMeResponse = {
  id: bigint;
  userName: string | null;
  email: string | null;
};

Parameters

• offset (number, optional): Starting position for pagination. Defaults to 0.

Returns

• Promise<Result<TUserFindResponse>>: A Result containing a paginated response with:
  • data: Array of user objects containing id, userName, and email
  • total: Total number of users in the system
  • offset: Current offset used for this page
  • Default limit: 100 users per page (hardcoded in the SDK)

Example

Basic Usage

const dbTest = zkdb.db('db_test');

// Get first page of users
const result = await dbTest.userList();

if (result.isOk()) {
  const users = result.unwrap();
  
  console.log(`Total users: ${users.total}`);
  console.log(`Showing: ${users.data.length} users`);
  
  users.data.forEach(user => {
    console.log(`- ${user.userName} (${user.email}) [ID: ${user.id}]`);
  });
} else {
  console.error('Error fetching users:', result.unwrapErr());
}

// Using unwrapOr for concise code
const users = (await dbTest.userList()).unwrapOr({ data: [], total: 0, offset: 0 });

Pagination Example

const dbTest = zkdb.db('db_test');

// Get first page (offset 0, limit 100)
const page1 = (await dbTest.userList(0)).unwrap();
console.log(`Page 1: ${page1.data.length} users`);

// Get second page (offset 100, limit 100)
const page2 = (await dbTest.userList(100)).unwrap();
console.log(`Page 2: ${page2.data.length} users`);

// Get third page (offset 200, limit 100)
const page3 = (await dbTest.userList(200)).unwrap();
console.log(`Page 3: ${page3.data.length} users`);

console.log(`Total users in system: ${page1.total}`);

Complete Pagination Example

const dbTest = zkdb.db('db_test');

async function getAllUsers() {
  const allUsers = [];
  let offset = 0;
  const limit = 100; // SDK default
  
  while (true) {
    const result = await dbTest.userList(offset);
    
    if (result.isErr()) {
      console.error('Error fetching users:', result.unwrapErr());
      break;
    }
    
    const page = result.unwrap();
    allUsers.push(...page.data);
    
    console.log(`Fetched ${page.data.length} users (offset: ${offset})`);
    
    // Break if we've fetched all users
    if (allUsers.length >= page.total) {
      break;
    }
    
    offset += limit;
  }
  
  return allUsers;
}

const allUsers = await getAllUsers();
console.log(`Total users fetched: ${allUsers.length}`);

Filtering Active Users

const dbTest = zkdb.db('db_test');

const users = (await dbTest.userList()).unwrap();

// Filter users with valid email addresses
const activeUsers = users.data.filter(user => 
  user.email !== null && user.userName !== null
);

console.log(`Active users: ${activeUsers.length} out of ${users.total}`);

// Display active users
activeUsers.forEach(user => {
  console.log(`✓ ${user.userName} - ${user.email}`);
});

Example Result

{
  "data": [
    {
      "id": 1n,
      "userName": "alice",
      "email": "[email protected]"
    },
    {
      "id": 2n,
      "userName": "bob",
      "email": "[email protected]"
    },
    {
      "id": 3n,
      "userName": "charlie",
      "email": "[email protected]"
    }
  ],
  "total": 156,
  "offset": 0
}

Usage in Examples

Adding Users to a Group

import { zkdb } from './connection';

const dbTest = zkdb.db('db_test');
const editorsGroup = dbTest.group('editors');

// Get users
const users = (await dbTest.userList()).unwrap();

if (users.data.length > 0) {
  // Get first 2 user IDs
  const userIds = users.data.map(u => u.id).slice(0, 2);
  
  // Add users to group
  (await editorsGroup.userAdd(userIds)).unwrap();
  console.log(`Added ${userIds.length} users to editors group`);
}

Displaying User Directory

import { zkdb } from './connection';

const dbTest = zkdb.db('db_test');

const users = (await dbTest.userList()).unwrap();

console.log('=== User Directory ===');
console.log(`Total: ${users.total} users\n`);

users.data.forEach((user, index) => {
  const position = users.offset + index + 1;
  console.log(`${position}. ${user.userName || 'N/A'}`);
  console.log(`   Email: ${user.email || 'N/A'}`);
  console.log(`   ID: ${user.id}\n`);
});

Notes

• Pagination Limit: The SDK hardcodes a limit of 100 users per page (defined as USER_LIST_LIMIT constant)
• Null Values: User fields (userName, email) can be null, so always check before using
• BigInt IDs: User IDs are returned as bigint type for consistency with database operations
• No Search: This endpoint does not support search/filtering. Use the offset parameter for pagination only

See Also

• User Operations: user() - Get or manage a specific user
• Group Management: groupList() - List all groups