trilium-api 1.0.1 → 1.0.2

package/src/mapper.ts

@@ -1,534 +0,0 @@
-/**
- * Trilium Note Mapper and Search Query Builder
- * 
- * Provides utilities for mapping Trilium notes to strongly-typed objects
- * and building type-safe search queries.
- */
-
-import type { TriliumNote } from './client.js';
-
-// ============================================================================
-// Search Query Builder Types
-// ============================================================================
-
-/**
- * Comparison operators for search conditions
- */
-export type ComparisonOperator = '=' | '!=' | '<' | '<=' | '>' | '>=' | '*=' | '=*' | '*=*';
-
-/**
- * A value with an optional comparison operator
- */
-export interface ConditionValue<T = string | number | boolean> {
-  value: T;
-  operator?: ComparisonOperator;
-}
-
-/**
- * Simple value or condition with operator
- */
-export type SearchValue = string | number | boolean | ConditionValue;
-
-/**
- * Base search conditions for labels, relations, and note properties.
- * Use template literal keys for labels (#) and relations (~).
- * Regular string keys are treated as note properties.
- */
-export type TriliumSearchConditions = {
-  /** Labels: use #labelName as key */
-  [key: `#${string}`]: SearchValue | undefined;
-} & {
-  /** Relations: use ~relationName as key */
-  [key: `~${string}`]: SearchValue | undefined;
-} & {
-  /** Note properties: use note.property as key or just property name */
-  [key: string]: SearchValue | undefined;
-};
-
-/**
- * Logical operators for combining search conditions
- */
-export interface TriliumSearchLogical {
-  /** Combine multiple conditions with AND */
-  AND?: TriliumSearchHelpers[];
-  /** Combine multiple conditions with OR */
-  OR?: TriliumSearchHelpers[];
-  /** Negate a condition */
-  NOT?: TriliumSearchHelpers;
-}
-
-/**
- * Complete search helpers combining conditions and logical operators.
- * Can contain field conditions AND/OR logical operators.
- */
-export type TriliumSearchHelpers = 
-  | TriliumSearchLogical
-  | (TriliumSearchConditions & Partial<TriliumSearchLogical>);
-
-/**
- * Builds a Trilium search query string from a structured helper object
- * 
- * @param helpers - The search conditions and logical operators
- * @returns A properly formatted Trilium search query string
- * 
- * @example
- * // Simple label search
- * buildSearchQuery({ '#blog': true })
- * // => '#blog'
- * 
- * @example
- * // Label with value
- * buildSearchQuery({ '#status': 'published' })
- * // => "#status = 'published'"
- * 
- * @example
- * // Complex AND/OR conditions
- * buildSearchQuery({
- *   AND: [
- *     { '#blog': true },
- *     { OR: [
- *       { '#status': 'published' },
- *       { '#status': 'featured' }
- *     ]}
- *   ]
- * })
- * // => "#blog AND (#status = 'published' OR #status = 'featured')"
- * 
- * @example
- * // Note properties with operators
- * buildSearchQuery({
- *   'note.type': 'text',
- *   '#wordCount': { value: 1000, operator: '>=' }
- * })
- * // => "note.type = 'text' AND #wordCount >= 1000"
- */
-export function buildSearchQuery(helpers: TriliumSearchHelpers): string {
-  // Handle logical operators
-  if ('AND' in helpers && Array.isArray(helpers.AND)) {
-    return helpers.AND.map((h) => {
-      const query = buildSearchQuery(h);
-      // Wrap in parentheses if it contains OR
-      return query.includes(' OR ') ? `(${query})` : query;
-    }).join(' AND ');
-  }
-
-  if ('OR' in helpers && Array.isArray(helpers.OR)) {
-    return helpers.OR.map((h) => {
-      const query = buildSearchQuery(h);
-      // Wrap in parentheses if it contains AND or OR
-      return query.includes(' AND ') || query.includes(' OR ') ? `(${query})` : query;
-    }).join(' OR ');
-  }
-
-  if ('NOT' in helpers && helpers.NOT !== undefined) {
-    const notValue = helpers.NOT;
-    // Type guard: check if it's a valid TriliumSearchHelpers object
-    if (typeof notValue === 'object' && notValue !== null && !('value' in notValue)) {
-      const query = buildSearchQuery(notValue);
-      return `not(${query})`;
-    }
-    // If it's a simple value, this shouldn't happen in valid usage
-    throw new Error('NOT operator requires a query object, not a simple value');
-  }
-
-  // Build individual conditions from TriliumSearchConditions
-  const parts: string[] = [];
-
-  for (const [key, value] of Object.entries(helpers)) {
-    if (value === undefined || value === null) continue;
-
-    // Handle labels (#)
-    if (key.startsWith('#')) {
-      const labelName = key.slice(1);
-
-      // Check if it's a nested property like #template.title
-      if (labelName.includes('.')) {
-        // For nested properties, use the full key as-is
-        if (typeof value === 'object' && 'value' in value) {
-          const operator = value.operator || '=';
-          const val = typeof value.value === 'string' ? `'${value.value}'` : value.value;
-          parts.push(`${key} ${operator} ${val}`);
-        } else if (typeof value === 'string') {
-          parts.push(`${key} = '${value}'`);
-        } else {
-          parts.push(`${key} = ${value}`);
-        }
-      } else {
-        // Simple label
-        if (value === true) {
-          parts.push(`#${labelName}`);
-        } else if (value === false) {
-          parts.push(`#!${labelName}`);
-        } else if (typeof value === 'object' && 'value' in value) {
-          const operator = value.operator || '=';
-          const val = typeof value.value === 'string' ? `'${value.value}'` : value.value;
-          parts.push(`#${labelName} ${operator} ${val}`);
-        } else if (typeof value === 'string') {
-          parts.push(`#${labelName} = '${value}'`);
-        } else {
-          parts.push(`#${labelName} = ${value}`);
-        }
-      }
-    }
-    // Handle relations (~)
-    else if (key.startsWith('~')) {
-      const relationName = key.slice(1);
-
-      // Check if it's a nested property like ~author.title
-      if (relationName.includes('.')) {
-        // For nested properties, use the full key as-is
-        if (typeof value === 'object' && 'value' in value) {
-          const operator = value.operator || '=';
-          const val = typeof value.value === 'string' ? `'${value.value}'` : value.value;
-          parts.push(`${key} ${operator} ${val}`);
-        } else if (typeof value === 'string') {
-          parts.push(`${key} = '${value}'`);
-        } else {
-          parts.push(`${key} = ${value}`);
-        }
-      } else {
-        // Simple relation - default to title search with contains
-        if (typeof value === 'object' && 'value' in value) {
-          const operator = value.operator || '*=*';
-          const val = typeof value.value === 'string' ? `'${value.value}'` : value.value;
-          parts.push(`${key} ${operator} ${val}`);
-        } else if (typeof value === 'string') {
-          parts.push(`${key} *=* '${value}'`);
-        }
-      }
-    }
-    // Handle note properties
-    else {
-      const path = key.startsWith('note.') ? key : `note.${key}`;
-
-      if (typeof value === 'object' && 'value' in value) {
-        const operator = value.operator || '=';
-        const val = typeof value.value === 'string' ? `'${value.value}'` : value.value;
-        parts.push(`${path} ${operator} ${val}`);
-      } else if (typeof value === 'string') {
-        parts.push(`${path} = '${value}'`);
-      } else if (typeof value === 'boolean') {
-        parts.push(`${path} = ${value}`);
-      } else {
-        parts.push(`${path} = ${value}`);
-      }
-    }
-  }
-
-  return parts.join(' AND ');
-}
-
-// ============================================================================
-// Mapper Types
-// ============================================================================
-
-/**
- * Transform function that converts a raw value into the target type
- * @template T - The target object type
- * @template K - The specific key in the target type
- */
-export type TransformFunction<T, K extends keyof T> = (value: unknown, note: TriliumNote) => T[K] | undefined;
-
-/**
- * Computed function that calculates a value from the partially mapped object
- * @template T - The target object type
- * @template K - The specific key in the target type
- */
-export type ComputedFunction<T, K extends keyof T> = (partial: Partial<T>, note: TriliumNote) => T[K] | undefined;
-
-/**
- * Field mapping configuration for a single property
- * Can be a simple string path, a detailed configuration object, or a computed value
- * 
- * @template T - The target object type
- * @template K - The specific key in the target type
- * 
- * @example
- * // Shorthand string path
- * title: 'note.title'
- * 
- * @example
- * // Full configuration
- * tags: {
- *   from: '#tags',
- *   transform: transforms.commaSeparated,
- *   default: [],
- *   required: false
- * }
- * 
- * @example
- * // Computed value
- * readTimeMinutes: {
- *   computed: (partial) => Math.ceil((partial.wordCount || 0) / 200)
- * }
- */
-export type FieldMapping<T, K extends keyof T = keyof T> =
-  | string // Shorthand: direct path like 'note.title' or '#label'
-  | {
-      /** Source path (string) or extractor function */
-      from: string | ((note: TriliumNote) => unknown);
-      /** Optional transform function to convert the raw value */
-      transform?: TransformFunction<T, K>;
-      /** Default value if extraction returns undefined */
-      default?: T[K];
-      /** Whether this field is required (throws if missing) */
-      required?: boolean;
-    }
-  | {
-      /** Computed function that calculates value from other mapped fields */
-      computed: ComputedFunction<T, K>;
-      /** Default value if computed returns undefined */
-      default?: T[K];
-    };
-
-/**
- * Complete mapping configuration for a type
- * Maps each property key to its field mapping configuration
- * 
- * @template T - The target object type to map to
- */
-export type MappingConfig<T> = {
-  [K in keyof T]?: FieldMapping<T, K>;
-};
-
-/**
- * Maps Trilium notes to strongly-typed objects using declarative field mappings
- * 
- * Supports:
- * - Direct property paths (note.title, note.noteId)
- * - Label attributes (#labelName)
- * - Relation attributes (~relationName)
- * - Custom extractor functions
- * - Transform functions
- * - Computed values from other fields
- * - Default values
- * - Required field validation
- * 
- * @template T - The target type to map notes to
- * 
- * @example
- * const mapper = new TriliumMapper<BlogPost>({
- *   title: 'note.title',
- *   slug: { from: '#slug', required: true },
- *   wordCount: { from: '#wordCount', transform: transforms.number, default: 0 },
- *   readTimeMinutes: {
- *     computed: (partial) => Math.ceil((partial.wordCount || 0) / 200)
- *   }
- * });
- * 
- * const posts = mapper.map(notes);
- */
-export class TriliumMapper<T> {
-  /** The mapping configuration for this mapper */
-  private readonly config: MappingConfig<T>;
-
-  /**
-   * Creates a new TriliumMapper instance
-   * @param config - The mapping configuration defining how to map note fields to the target type
-   */
-  constructor(config: MappingConfig<T>) {
-    this.config = config;
-  }
-
-  /**
-   * Merges multiple mapping configurations into a single configuration
-   * Later configs override earlier ones for the same keys
-   * Supports merging configs from base types into derived types
-   * 
-   * @template T - The target type for the merged configuration
-   * @param configs - One or more mapping configurations to merge
-   * @returns A new merged mapping configuration
-   * 
-   * @example
-   * const merged = TriliumMapper.merge<BlogPost>(
-   *   StandardNoteMapping,
-   *   BlogSpecificMapping,
-   *   OverrideMapping
-   * );
-   */
-  static merge<T>(...configs: (Partial<MappingConfig<T>> | MappingConfig<unknown>)[]): MappingConfig<T> {
-    return Object.assign({}, ...configs) as MappingConfig<T>;
-  }
-
-  /**
-   * Maps a single note to the target type
-   * @param note - The Trilium note to map
-   * @returns The mapped object of type T
-   */
-  map(note: TriliumNote): T;
-
-  /**
-   * Maps an array of notes to the target type
-   * @param notes - The Trilium notes to map
-   * @returns An array of mapped objects of type T
-   */
-  map(notes: TriliumNote[]): T[];
-
-  /**
-   * Maps one or more Trilium notes to the target type
-   * @param noteOrNotes - A single note or array of notes to map
-   * @returns A single mapped object or array of mapped objects
-   */
-  map(noteOrNotes: TriliumNote | TriliumNote[]): T | T[] {
-    return Array.isArray(noteOrNotes) ? noteOrNotes.map((note) => this.mapSingle(note)) : this.mapSingle(noteOrNotes);
-  }
-
-  /**
-   * Maps a single note to the target type using the configured field mappings
-   * Processes in two passes: first regular fields, then computed fields
-   * @param note - The Trilium note to map
-   * @returns The mapped object
-   * @throws Error if a required field is missing
-   * @private
-   */
-  private mapSingle(note: TriliumNote): T {
-    const result = {} as Record<keyof T, unknown>;
-    const computedFields: [keyof T, { computed: ComputedFunction<T, keyof T>; default?: T[keyof T] }][] = [];
-
-    // First pass: process regular fields
-    for (const [key, fieldMapping] of Object.entries(this.config) as [keyof T, FieldMapping<T>][]) {
-      if (!fieldMapping) continue;
-
-      // Check if it's a computed field
-      if (typeof fieldMapping === 'object' && 'computed' in fieldMapping) {
-        computedFields.push([key, fieldMapping]);
-        continue;
-      }
-
-      // Normalize shorthand to full mapping
-      const mapping = typeof fieldMapping === 'string' ? { from: fieldMapping } : fieldMapping;
-
-      // Extract value
-      let value: unknown = typeof mapping.from === 'function' ? mapping.from(note) : this.extractValue(note, mapping.from);
-
-      // Transform
-      if (mapping.transform) {
-        value = mapping.transform(value, note);
-      }
-
-      // Default
-      if (value === undefined && mapping.default !== undefined) {
-        value = mapping.default;
-      }
-
-      // Validate required
-      if (mapping.required && value === undefined) {
-        throw new Error(`Required field '${String(key)}' missing from note ${note.noteId} (${note.title})`);
-      }
-
-      result[key] = value;
-    }
-
-    // Second pass: process computed fields
-    for (const [key, mapping] of computedFields) {
-      let value = mapping.computed(result as Partial<T>, note);
-
-      // Default
-      if (value === undefined && mapping.default !== undefined) {
-        value = mapping.default;
-      }
-
-      result[key] = value;
-    }
-
-    return result as T;
-  }
-
-  /**
-   * Extracts a value from a note using a string path
-   * 
-   * Supports:
-   * - Label attributes: #labelName
-   * - Relation attributes: ~relationName
-   * - Note properties: note.property.path
-   * 
-   * @param note - The Trilium note to extract from
-   * @param path - The path string indicating where to extract the value
-   * @returns The extracted value or undefined if not found
-   * @private
-   * 
-   * @example
-   * extractValue(note, 'note.title') // => note.title
-   * extractValue(note, '#slug')      // => label attribute 'slug'
-   * extractValue(note, '~template')  // => relation attribute 'template'
-   */
-  private extractValue(note: TriliumNote, path: string): unknown {
-    if (!path) return undefined;
-
-    // Label attribute: #labelName
-    if (path.startsWith('#')) {
-      return note.attributes?.find((attr) => attr.type === 'label' && attr.name === path.slice(1))?.value;
-    }
-
-    // Relation attribute: ~relationName
-    if (path.startsWith('~')) {
-      return note.attributes?.find((attr) => attr.type === 'relation' && attr.name === path.slice(1))?.value;
-    }
-
-    // Note property: note.property.path
-    if (path.startsWith('note.')) {
-      return path.slice(5).split('.').reduce((obj, key) => (obj as Record<string, unknown>)?.[key], note as unknown);
-    }
-
-    return undefined;
-  }
-}
-
-// ============================================================================
-// Common Transform Functions
-// ============================================================================
-
-/**
- * Common transform functions for use with TriliumMapper
- */
-export const transforms = {
-  /** Convert to number */
-  number: (value: unknown): number | undefined => {
-    if (value === undefined || value === null || value === '') return undefined;
-    const num = Number(value);
-    return isNaN(num) ? undefined : num;
-  },
-
-  /** Convert to boolean */
-  boolean: (value: unknown): boolean | undefined => {
-    if (value === undefined || value === null) return undefined;
-    if (typeof value === 'boolean') return value;
-    if (typeof value === 'string') {
-      const lower = value.toLowerCase();
-      if (lower === 'true' || lower === '1' || lower === 'yes') return true;
-      if (lower === 'false' || lower === '0' || lower === 'no') return false;
-    }
-    return undefined;
-  },
-
-  /** Split comma-separated string into array */
-  commaSeparated: (value: unknown): string[] | undefined => {
-    if (value === undefined || value === null || value === '') return undefined;
-    if (typeof value !== 'string') return undefined;
-    return value.split(',').map((s) => s.trim()).filter(Boolean);
-  },
-
-  /** Parse JSON string */
-  json: <T>(value: unknown): T | undefined => {
-    if (value === undefined || value === null || value === '') return undefined;
-    if (typeof value !== 'string') return undefined;
-    try {
-      return JSON.parse(value) as T;
-    } catch {
-      return undefined;
-    }
-  },
-
-  /** Parse date string */
-  date: (value: unknown): Date | undefined => {
-    if (value === undefined || value === null || value === '') return undefined;
-    const date = new Date(String(value));
-    return isNaN(date.getTime()) ? undefined : date;
-  },
-
-  /** Trim whitespace from string */
-  trim: (value: unknown): string | undefined => {
-    if (value === undefined || value === null) return undefined;
-    return String(value).trim() || undefined;
-  },
-};

package/tsconfig.json

@@ -1,42 +0,0 @@
-{
-  // Visit https://aka.ms/tsconfig to read more about this file
-  "compilerOptions": {
-    // File Layout
-    // "rootDir": "./src",
-    // "outDir": "./dist",
-
-    // Environment Settings
-    // See also https://aka.ms/tsconfig/module
-    "module": "nodenext",
-    "target": "esnext",
-    "types": ["node"],
-    // For nodejs:
-    // "lib": ["esnext"],
-
-    // Other Outputs
-    "sourceMap": true,
-    "declaration": true,
-    "declarationMap": true,
-
-    // Stricter Typechecking Options
-    "noUncheckedIndexedAccess": true,
-    "exactOptionalPropertyTypes": true,
-
-    // Style Options
-    // "noImplicitReturns": true,
-    // "noImplicitOverride": true,
-    // "noUnusedLocals": true,
-    // "noUnusedParameters": true,
-    // "noFallthroughCasesInSwitch": true,
-    // "noPropertyAccessFromIndexSignature": true,
-
-    // Recommended Options
-    "strict": true,
-    "jsx": "react-jsx",
-    "verbatimModuleSyntax": true,
-    "isolatedModules": true,
-    "noUncheckedSideEffectImports": true,
-    "moduleDetection": "force",
-    "skipLibCheck": true,
-  }
-}