tessl/npm-payload

Node, React and MongoDB Headless CMS and Application Framework

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

User Preferences System

Name: tessl/npm-payload
Author: tessl

User preferences system for storing and managing user-specific settings, UI state, and document preferences in Payload CMS. This system allows users to persist their preferences across sessions, including collapsed fields, admin panel settings, and custom application state.

Capabilities

Find Preference

Retrieves a user preference by key.

/**
 * Find a user preference by key
 * @param options - Options for finding the preference
 * @returns Promise resolving to the preference value or null
 */
function findPreference<T = any>(options: PreferenceRequest): Promise<T | null>;

interface PreferenceRequest {
  /** The preference key to find */
  key: string;
  /** The user object */
  user: User;
  /** Express request object */
  req: PayloadRequest;
  /** Whether to override access control */
  overrideAccess?: boolean;
}

Usage Examples:

import payload from "payload";

// Find user's collapsed field preferences
const collapsedFields = await payload.findPreference({
  key: "posts-fields",
  user: req.user,
  req,
});

// Find custom user settings
const dashboardSettings = await payload.findPreference({
  key: "dashboard-layout",
  user: req.user,
  req,
});

Update Preference

Updates or creates a user preference.

/**
 * Update or create a user preference
 * @param options - Options for updating the preference
 * @returns Promise resolving to the updated preference
 */
function updatePreference<T = any>(options: PreferenceUpdateRequest): Promise<Preference>;

interface PreferenceUpdateRequest extends PreferenceRequest {
  /** The value to store for this preference */
  value: T;
}

Usage Examples:

import payload from "payload";

// Update collapsed field state
await payload.updatePreference({
  key: "posts-fields",
  value: {
    fields: {
      content: { collapsed: ["advancedOptions"] },
      meta: { collapsed: ["seo", "social"] },
    },
  },
  user: req.user,
  req,
});

// Update custom settings
await payload.updatePreference({
  key: "theme-preference",
  value: { theme: "dark", sidebarCollapsed: true },
  user: req.user,
  req,
});

Delete Preference

Deletes a user preference by key.

/**
 * Delete a user preference by key
 * @param options - Options for deleting the preference
 * @returns Promise resolving to the deleted preference or null
 */
function deletePreference(options: PreferenceRequest): Promise<Preference | null>;

Usage Examples:

import payload from "payload";

// Reset user preferences
await payload.deletePreference({
  key: "dashboard-layout",
  user: req.user,
  req,
});

Types

/**
 * Base preference document structure
 */
interface Preference {
  /** User ID that owns this preference */
  user: string;
  /** Collection slug the user belongs to */
  userCollection: string;
  /** Unique key for the preference */
  key: string;
  /** The stored preference value */
  value: { [key: string]: unknown } | unknown;
  /** Creation timestamp */
  createdAt?: Date;
  /** Last update timestamp */
  updatedAt?: Date;
}

/**
 * Document-level preferences for admin UI
 */
interface DocumentPreferences {
  /** Field-specific preferences */
  fields: FieldsPreferences;
}

/**
 * Field preferences including collapse states
 */
interface FieldsPreferences {
  [fieldName: string]: {
    /** Array of collapsed field paths */
    collapsed: CollapsedPreferences;
  };
}

/**
 * Array of field paths that are collapsed
 */
type CollapsedPreferences = string[];

Common Use Cases

Admin UI State Persistence

Preferences are commonly used to persist admin panel UI state across sessions:

// Field collapse states
const fieldPrefs: DocumentPreferences = {
  fields: {
    content: { 
      collapsed: ["metadata", "seo"] 
    },
    sidebar: { 
      collapsed: ["relatedPosts"] 
    },
  },
};

await payload.updatePreference({
  key: `${collection}-fields`,
  value: fieldPrefs,
  user: req.user,
  req,
});

Custom Application Settings

Store custom user settings for your application:

// Theme and layout preferences
await payload.updatePreference({
  key: "app-settings",
  value: {
    theme: "dark",
    language: "en",
    timezone: "America/New_York",
    dashboardWidgets: ["analytics", "recent-posts"],
  },
  user: req.user,
  req,
});

Per-Collection Settings

Maintain different settings for each collection:

// Different list view settings per collection
await payload.updatePreference({
  key: "posts-list-view",
  value: {
    columns: ["title", "status", "author", "updatedAt"],
    limit: 25,
    sort: "-updatedAt",
  },
  user: req.user,
  req,
});

await payload.updatePreference({
  key: "media-list-view", 
  value: {
    columns: ["filename", "alt", "filesize", "createdAt"],
    limit: 50,
    sort: "filename",
  },
  user: req.user,
  req,
});

Install with Tessl CLI