/**
* Logseq operations module.
*
* This module provides high-level operations for interacting with Logseq,
* organized into logical groups:
* - Base operations (pages, blocks, search, query)
* - Task management (getTasks, createTask, markTask, etc.)
* - Journal operations (getToday, appendToToday, getRecentJournals)
* - Search & discovery (findRelatedPages, getBlockBacklinks)
*
* @module
*/
import { LogseqClient } from "../logseq-client.js";
import type {
Task,
TaskMarker,
TaskPriority,
GetTasksOptions,
CreateTaskOptions,
SetTaskDeadlineOptions,
SetTaskScheduledOptions,
SearchTasksOptions,
TaskStats,
GetTasksDueSoonOptions,
MarkTasksResult,
JournalPage,
GetRecentJournalsOptions,
BlockBacklinks,
PageLinks,
Block,
ListTemplatesResult,
Template,
CreatePageFromTemplateOptions,
CreatePageFromTemplateResult,
CreateBlocksFromTemplateOptions,
CreateBlocksFromTemplateResult,
} from "../types.js";
// Import base class
import { LogseqOperations as BaseOperations } from "./base.js";
// Import task operations
import {
getTasks as _getTasks,
createTask as _createTask,
markTask as _markTask,
markTasks as _markTasks,
setTaskPriority as _setTaskPriority,
setTaskDeadline as _setTaskDeadline,
setTaskScheduled as _setTaskScheduled,
searchTasks as _searchTasks,
getOverdueTasks as _getOverdueTasks,
getTasksDueSoon as _getTasksDueSoon,
getTaskStats as _getTaskStats,
} from "./tasks.js";
// Import journal operations
import {
getToday as _getToday,
appendToToday as _appendToToday,
getRecentJournals as _getRecentJournals,
findRelatedPages as _findRelatedPages,
getBlockBacklinks as _getBlockBacklinks,
} from "./journals.js";
// Import template operations
import {
listTemplates as _listTemplates,
getTemplate as _getTemplate,
createPageFromTemplate as _createPageFromTemplate,
createBlocksFromTemplate as _createBlocksFromTemplate,
} from "./templates.js";
// Re-export helpers
export { parseTaskContent, buildTaskContent, formatJournalName } from "./helpers.js";
/**
* High-level operations for Logseq.
*
* This class provides a simplified interface for common Logseq operations,
* with automatic error handling that throws typed exceptions instead of
* returning error responses.
*
* @example
* ```typescript
* import { LogseqClient, LogseqOperations } from "@logseq-ai/core";
*
* const client = new LogseqClient();
* const ops = new LogseqOperations(client);
*
* // Search for pages
* const results = await ops.search("meeting");
*
* // Get tasks
* const tasks = await ops.getTasks();
*
* // Append to today's journal
* await ops.appendToToday("Meeting notes");
* ```
*/
export class LogseqOperations extends BaseOperations {
constructor(client: LogseqClient) {
super(client);
}
// ===========================================================================
// Task Management Operations
// ===========================================================================
/**
* Retrieves tasks from Logseq.
*
* @param options - Filter options
* @returns Array of tasks
*/
async getTasks(options: GetTasksOptions = {}): Promise<Task[]> {
return _getTasks(this, options);
}
/**
* Creates a new task.
*
* @param options - Task creation options
* @returns The created task
*/
async createTask(options: CreateTaskOptions): Promise<Task> {
return _createTask(this, options);
}
/**
* Changes a task's marker (status).
*
* @param uuid - UUID of the task block
* @param marker - New marker (TODO, DOING, DONE, or CANCELED)
*/
async markTask(uuid: string, marker: TaskMarker): Promise<void> {
return _markTask(this, uuid, marker);
}
/**
* Changes multiple tasks' markers (status) in a single operation.
*
* @param uuids - Array of task block UUIDs to update
* @param marker - New marker for all tasks
* @returns Result with successful and failed UUIDs
*/
async markTasks(uuids: string[], marker: TaskMarker): Promise<MarkTasksResult> {
return _markTasks(this, uuids, marker);
}
/**
* Sets or removes a task's priority.
*
* @param uuid - UUID of the task block
* @param priority - Priority level (A, B, C) or null to remove
*/
async setTaskPriority(uuid: string, priority: TaskPriority | null): Promise<void> {
return _setTaskPriority(this, uuid, priority);
}
/**
* Sets or removes a task's deadline.
*
* @param options - Deadline options
*/
async setTaskDeadline(options: SetTaskDeadlineOptions): Promise<void> {
return _setTaskDeadline(this, options);
}
/**
* Sets or removes a task's scheduled date.
*
* @param options - Scheduled options
*/
async setTaskScheduled(options: SetTaskScheduledOptions): Promise<void> {
return _setTaskScheduled(this, options);
}
/**
* Searches for tasks matching a query string.
*
* @param options - Search options
* @returns Array of matching tasks
*/
async searchTasks(options: SearchTasksOptions): Promise<Task[]> {
return _searchTasks(this, options);
}
/**
* Gets tasks that are past their deadline.
*
* @returns Array of overdue tasks
*/
async getOverdueTasks(): Promise<Task[]> {
return _getOverdueTasks(this);
}
/**
* Gets tasks due within a specified number of days.
*
* @param options - Options including days to look ahead
* @returns Array of tasks due soon
*/
async getTasksDueSoon(options?: GetTasksDueSoonOptions): Promise<Task[]> {
return _getTasksDueSoon(this, options);
}
/**
* Gets aggregated statistics about tasks.
*
* @param pageName - Optional page to filter stats to
* @returns Task statistics
*/
async getTaskStats(pageName?: string): Promise<TaskStats> {
return _getTaskStats(this, pageName);
}
// ===========================================================================
// Journal Operations
// ===========================================================================
/**
* Gets or creates today's journal page.
*
* @returns Today's journal page with content
*/
async getToday(): Promise<JournalPage> {
return _getToday(this);
}
/**
* Appends content to today's journal page.
*
* @param content - Content to append
* @returns The created block
*/
async appendToToday(content: string): Promise<Block> {
return _appendToToday(this, content);
}
/**
* Gets recent journal entries.
*
* @param options - Options including number of days
* @returns Array of journal pages
*/
async getRecentJournals(options?: GetRecentJournalsOptions): Promise<JournalPage[]> {
return _getRecentJournals(this, options);
}
// ===========================================================================
// Search & Discovery Operations
// ===========================================================================
/**
* Finds pages linked to and from a given page.
*
* @param pageName - Name of the page
* @returns Object containing backlinks and forward links
*/
async findRelatedPages(pageName: string): Promise<PageLinks> {
return _findRelatedPages(this, pageName);
}
/**
* Finds all blocks that reference a given block.
*
* @param uuid - UUID of the block
* @returns Block backlinks information
*/
async getBlockBacklinks(uuid: string): Promise<BlockBacklinks> {
return _getBlockBacklinks(this, uuid);
}
// ===========================================================================
// Template Operations
// ===========================================================================
/**
* Lists all templates in the graph.
*
* @returns List of templates with basic info
*/
async listTemplates(): Promise<ListTemplatesResult> {
return _listTemplates(this);
}
/**
* Gets detailed information about a specific template.
*
* @param templateName - Name of the template to retrieve
* @returns Template details or null if not found
*/
async getTemplate(templateName: string): Promise<Template | null> {
return _getTemplate(this, templateName);
}
/**
* Creates a new page using a template.
*
* @param options - Options including page name, template name, and optional variables
* @returns Result with created page and metadata
*/
async createPageFromTemplate(
options: CreatePageFromTemplateOptions
): Promise<CreatePageFromTemplateResult> {
return _createPageFromTemplate(this, options);
}
/**
* Creates blocks from a template on an existing page.
*
* @param options - Options including page name, template name, insert position, and variables
* @returns Result with created blocks and metadata
*/
async createBlocksFromTemplate(
options: CreateBlocksFromTemplateOptions
): Promise<CreateBlocksFromTemplateResult> {
return _createBlocksFromTemplate(this, options);
}
}
