trilium-api 1.0.1 → 1.0.4

package/README.md

@@ -10,6 +10,7 @@ A type-safe TypeScript client for the [Trilium Notes](https://github.com/Trilium
 - [API Reference](#api-reference)
 - [Search Query Builder](#search-query-builder)
 - [Note Mapper](#note-mapper)
+- [Search and Map](#search-and-map)
 - [Types](#types)
 - [Error Handling](#error-handling)
 - [Demo](#demo)
@@ -23,6 +24,7 @@ A type-safe TypeScript client for the [Trilium Notes](https://github.com/Trilium
 -  **Lightweight** - Built on [openapi-fetch](https://openapi-ts.dev/openapi-fetch/) (~6kb)
 -  **Query Builder** - Type-safe search query construction
 -  **Mapper** - Declarative note-to-object mapping with transforms
+-  **StandardNote** - Consistent base fields (id, title, dates) on all mapped types
 
 ## Installation
 
@@ -38,7 +40,7 @@ pnpm add trilium-api
 import { createTriliumClient } from 'trilium-api';
 
 const client = createTriliumClient({
-  baseUrl: 'http://localhost:37840',
+  baseUrl: 'http://localhost:8080',
   apiKey: 'your-etapi-token',
 });
 
@@ -65,7 +67,7 @@ const { data: results } = await client.GET('/notes', {
 import { createTriliumClient } from 'trilium-api';
 
 const client = createTriliumClient({
-  baseUrl: 'http://localhost:37840', // Your Trilium server URL
+  baseUrl: 'http://localhost:8080', // Your Trilium server URL
   apiKey: 'your-etapi-token',        // ETAPI token from Trilium settings
 });
 ```
@@ -261,54 +263,61 @@ const { data } = await client.GET('/notes', {
 
 ## Note Mapper
 
-Map Trilium notes to strongly-typed objects using declarative field mappings:
+Map Trilium notes to strongly-typed objects using declarative field mappings.
+
+### StandardNote Base Type
+
+All mapped types should extend `StandardNote`, which provides consistent base fields:
 
 ```typescript
-import { TriliumMapper, transforms } from 'trilium-api';
+import type { StandardNote } from 'trilium-api';
+
+// StandardNote includes:
+// - id: string (note ID)
+// - title: string (note title)  
+// - dateCreatedUtc: Date
+// - dateLastModifiedUtc: Date
 
-// Define your target type
-interface BlogPost {
-  id: string;
-  title: string;
+interface BlogPost extends StandardNote {
+  slug: string;
+  tags: string[];
+  isPublished: boolean;
+}
+```
+
+### Using TriliumMapper Directly
+
+For standalone mapping (outside of `searchAndMap`), use `TriliumMapper`:
+
+```typescript
+import { TriliumMapper, StandardNoteMapping, transforms, type StandardNote } from 'trilium-api';
+
+interface BlogPost extends StandardNote {
   slug: string;
-  publishDate: Date;
   wordCount: number;
   readTimeMinutes: number;
   tags: string[];
   isPublished: boolean;
 }
 
-// Create a mapper
-const blogMapper = new TriliumMapper<BlogPost>({
-  // Simple property mapping (shorthand)
-  id: 'note.noteId',
-  title: 'note.title',
-  
-  // Label attribute with required validation
-  slug: { from: '#slug', required: true },
-  
-  // Transform string to Date
-  publishDate: { from: '#publishDate', transform: transforms.date },
-  
-  // Transform string to number with default
-  wordCount: { from: '#wordCount', transform: transforms.number, default: 0 },
-  
-  // Computed field based on other mapped values
-  readTimeMinutes: {
-    computed: (partial) => Math.ceil((partial.wordCount || 0) / 200),
-  },
-  
-  // Transform comma-separated string to array
-  tags: { from: '#tags', transform: transforms.commaSeparated, default: [] },
-  
-  // Transform to boolean
-  isPublished: { from: '#published', transform: transforms.boolean, default: false },
-});
+// Merge StandardNoteMapping with your custom fields
+const blogMapper = new TriliumMapper<BlogPost>(
+  TriliumMapper.merge(
+    StandardNoteMapping,
+    {
+      slug: { from: '#slug', required: true },
+      wordCount: { from: '#wordCount', transform: transforms.number, default: 0 },
+      readTimeMinutes: {
+        computed: (partial) => Math.ceil((partial.wordCount || 0) / 200),
+      },
+      tags: { from: '#tags', transform: transforms.commaSeparated, default: [] },
+      isPublished: { from: '#published', transform: transforms.boolean, default: false },
+    }
+  )
+);
 
-// Map a single note
+// Map notes
 const post = blogMapper.map(note);
-
-// Map an array of notes
 const posts = blogMapper.map(notes);
 ```
 
@@ -369,44 +378,149 @@ const posts = blogMapper.map(notes);
 | `transforms.date` | Parse date string | `"2024-01-15"` → `Date` |
 | `transforms.trim` | Trim whitespace | `"  hello  "` → `"hello"` |
 
-### Merging Configurations
+## Search and Map
 
-Reuse and extend mapping configurations:
+The `searchAndMap` method combines searching and mapping in a single call. It **automatically includes `StandardNoteMapping`**, so you only need to define your custom fields!
 
 ```typescript
-// Base configuration for common fields
-const baseMapping = {
-  id: 'note.noteId',
-  title: 'note.title',
-  createdAt: { from: 'note.utcDateCreated', transform: transforms.date },
-};
+import { createTriliumClient, transforms, type StandardNote, type CustomMapping } from 'trilium-api';
+
+const client = createTriliumClient({
+  baseUrl: 'http://localhost:8080',
+  apiKey: 'your-etapi-token',
+});
+
+// Extend StandardNote with your custom fields
+interface BlogPost extends StandardNote {
+  slug: string;
+  published: boolean;
+}
 
-// Extended configuration for blog posts
-const blogMapping = {
+// Use CustomMapping<T> for clean typing - excludes StandardNote fields automatically
+const blogMapping: CustomMapping<BlogPost> = {
   slug: '#slug',
-  tags: { from: '#tags', transform: transforms.commaSeparated, default: [] },
+  published: { from: '#published', transform: transforms.boolean, default: false },
 };
 
-// Merge configurations
-const merged = TriliumMapper.merge<BlogPost>(baseMapping, blogMapping);
-const mapper = new TriliumMapper<BlogPost>(merged);
+// Just pass your custom mapping - StandardNoteMapping is auto-merged!
+const { data, failures } = await client.searchAndMap<BlogPost>({
+  query: { '#blog': true, '#published': true },
+  mapping: blogMapping,
+  limit: 10,
+  orderBy: 'dateModified',
+  orderDirection: 'desc',
+});
+
+// Each post has: id, title, dateCreatedUtc, dateLastModifiedUtc, slug, published
+data.forEach(post => {
+  console.log(`${post.title} (${post.id}) - ${post.slug}`);
+});
+
+// Check for mapping failures
+if (failures.length > 0) {
+  console.warn(`${failures.length} notes failed to map:`);
+  failures.forEach(f => console.warn(`  - ${f.noteTitle}: ${f.reason}`));
+}
+```
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `query` | `string \| object` | Search query string or structured query object |
+| `mapping` | `CustomMapping<T>` | Field mapping for your custom fields (StandardNote fields auto-merged) |
+| `limit` | `number` | Maximum number of results |
+| `orderBy` | `string` | Field to order by (e.g., `'dateModified'`, `'title'`) |
+| `orderDirection` | `'asc' \| 'desc'` | Sort direction |
+| `fastSearch` | `boolean` | Enable fast search mode (less accurate but faster) |
+
+### Return Value
+
+```typescript
+{
+  data: T[],              // Successfully mapped objects
+  failures: MappingFailure[]  // Notes that failed to map
+}
+```
+
+### Handling Failures
+
+When a note fails to map (e.g., missing required field, transform error), it's added to the `failures` array instead of throwing:
+
+```typescript
+interface MappingFailure {
+  noteId: string;    // The note ID that failed
+  noteTitle: string; // The note title for identification
+  reason: string;    // Error message explaining the failure
+  note: TriliumNote; // The original note object for debugging
+}
+```
+
+This allows you to process partial results while still knowing which notes had issues:
+
+```typescript
+interface BlogPost extends StandardNote {
+  slug: string;
+}
+
+const { data, failures } = await client.searchAndMap<BlogPost>({
+  query: '#blog',
+  mapping: {
+    slug: { from: '#slug', required: true }, // Will fail if missing
+  },
+});
+
+// data contains all successfully mapped posts
+// failures contains notes missing the required #slug label
+```
+
+### Error Handling
+
+API or network errors throw an exception:
+
+```typescript
+try {
+  const { data, failures } = await client.searchAndMap<BlogPost>({
+    query: '#blog',
+    mapping: blogMapping,
+  });
+} catch (err) {
+  console.error('Search failed:', err);
+}
 ```
 
 ## Types
 
-The package exports all types from the OpenAPI specification:
+The package exports a focused set of types for common use cases:
 
 ```typescript
-import type {
+// Main imports for typical usage
+import { 
+  createTriliumClient, 
+  transforms, 
+  buildSearchQuery,
+} from 'trilium-api';
+
+import type { 
+  // Your mapped types should extend this
+  StandardNote,
+  // For typing your custom field mappings
+  CustomMapping,
+  // For typing query objects
+  TriliumSearchHelpers,
+  // For error handling
+  MappingFailure,
+  // Trilium entity types (for API responses)
   TriliumNote,
   TriliumBranch,
   TriliumAttribute,
   TriliumAttachment,
   TriliumAppInfo,
-  paths,
-  components,
-  operations,
 } from 'trilium-api';
+
+// Advanced: for standalone TriliumMapper usage (outside searchAndMap)
+import { TriliumMapper, StandardNoteMapping } from 'trilium-api';
+import type { MappingConfig } from 'trilium-api';
 ```
 
 ## Error Handling
@@ -620,7 +734,7 @@ function createMockResponse(body: any, status = 200, contentType = 'application/
 
 describe('my new feature', () => {
   const config = {
-    baseUrl: 'http://localhost:37840',
+    baseUrl: 'http://localhost:8080',
     apiKey: 'test-api-key',
   };
 
@@ -647,7 +761,7 @@ describe('my new feature', () => {
 
     // 4. Verify the request (openapi-fetch uses Request objects)
     const request = mockFetch.mock.calls[0]![0] as Request;
-    expect(request.url).toBe('http://localhost:37840/etapi/notes/test123');
+    expect(request.url).toBe('http://localhost:8080/etapi/notes/test123');
     expect(request.method).toBe('GET');
     expect(request.headers.get('Authorization')).toBe('test-api-key');
   });