# Using npm
npm install @type32/obsidian-bases-parser

# Using yarn
yarn add @type32/obsidian-bases-parser

# Using pnpm
pnpm add @type32/obsidian-bases-parser

# Using bun
bun add @type32/obsidian-bases-parser

import { createBase, PresetFilters, PresetFormulas } from './index';

const myBase = createBase()
  .withFilters(PresetFilters.byTag('project'))
  .addFormula('days_old', PresetFormulas.daysOld())
  .addFormula('status_icon', PresetFormulas.statusIcon())
  .addTableView('Active Projects', {
    order: ['file.name', 'status', 'formula.status_icon'],
    filters: PresetFilters.byStatus('active'),
  })
  .build();

import { createReactiveBase, PresetFilters, PresetFormulas } from './index';

const myBase = createReactiveBase()
  .addFilter(PresetFilters.byTag('project'))
  .addFormula('days_old', PresetFormulas.daysOld())
  .addFormula('status_icon', PresetFormulas.statusIcon())
  .addTableView('Active Projects', {
    order: ['file.name', 'status', 'formula.status_icon'],
    filters: PresetFilters.byStatus('active'),
  });

// Can be modified later!
myBase.addFormula('priority_label', PresetFormulas.priorityLabel());
myBase.setViewOrder('Active Projects', ['formula.priority_label', 'file.name']);

// Convert to YAML
const yaml = myBase.toYAML();

import { parseFilter, parseFilterExpression, evaluateFilter, validateFilter } from './index';

// Parse a filter expression into a FilterExpObject with extracted components
const parsed = parseFilterExpression('file.hasTag("book") && status == "reading"');

// Access extracted components for programmatic use
if (parsed.fileMethods.includes('hasTag')) {
  console.log('Tags referenced:', parsed.referencedTags); // ['book']
}

if (parsed.noteProperties.includes('status')) {
  console.log('Filter uses status property');
}

for (const comparison of parsed.comparisons) {
  console.log(`${comparison.left.name} ${comparison.operator} ${comparison.right.raw}`);
}

// Parse into AST (lower-level)
const result = parseFilter('file.hasTag("book") && status == "reading"');

// Evaluate against a context
const context = {
  file: {
    name: 'My Book.md',
    tags: ['book', 'reading'],
    // ... other file properties
  },
  note: {
    status: 'reading',
  },
};

const evaluation = evaluateFilter('file.hasTag("book")', context);
console.log(evaluation); // { type: 'BOOLEAN', value: true }

// Validate a filter
const validation = validateFilter({
  and: ['status == "done"', 'priority > 3'],
});

import { serializeToYAML } from './index';

const yaml = serializeToYAML(myBase);
console.log(yaml);
// Output:
// filters:
//   and:
//     - file.hasTag("project")
// formulas:
//   days_old: '((now() - file.ctime) / 86400000).round(0)'
// ...

import { Filter, FilterObject } from './index';

const simpleFilter: Filter = 'status == "done"';

const complexFilter: Filter = {
  or: [
    'file.hasTag("important")',
    {
      and: [
        'priority >= 3',
        {
          not: ['file.hasTag("archived")'],
        },
      ],
    },
  ],
};

import { View, TableView, CardsView, ListView, MapView } from './index';

const tableView: TableView = {
  type: 'table',
  name: 'My Table',
  order: ['file.name', 'status', 'due'],
  filters: { and: ['status != "done"'] },
  groupBy: { property: 'status', direction: 'ASC' },
  summaries: { priority: 'Average' },
  sort: [
    { property: 'file.name', direction: 'ASC' },
    { property: 'due', direction: 'DESC' },
  ],
  columnSize: {
    'file.name': 300,
    'status': 150,
  },
};

const cardsView: CardsView = {
  type: 'cards',
  name: 'Project Cards',
  order: ['priority', 'file.name'],
  cardSize: 250,
  image: 'cover',
  imageFit: 'cover',
  imageAspectRatio: 1.4,
};

import { Formulas } from './index';

const formulas: Formulas = {
  days_until_due: 'if(due, ((date(due) - today()) / 86400000).round(0), "")',
  is_overdue: 'if(due, date(due) < today() && status != "done", false)',
  priority_label: 'if(priority == 1, "🔴 High", if(priority == 2, "🟡 Medium", "🟢 Low"))',
};

import { PresetFilters } from './index';

PresetFilters.byTag('project');           // 'file.hasTag("project")'
PresetFilters.byExtension('md');          // 'file.ext == "md"'
PresetFilters.inFolder('Notes');          // 'file.inFolder("Notes")'
PresetFilters.modifiedWithin(7);          // 'file.mtime > now() - "7d"'
PresetFilters.byProperty('status', 'active'); // 'status == "active"'

import { PresetFormulas } from './index';

PresetFormulas.daysUntilDue();            // Days until due date
PresetFormulas.isOverdue();               // Check if overdue
PresetFormulas.lastModified();            // Relative modification time
PresetFormulas.priorityLabel();           // Priority with icons
PresetFormulas.statusIcon();              // Status with icons
PresetFormulas.formatCurrency('price');   // Format as currency

import { PresetSummaries } from './index';

PresetSummaries.customAverage(2);         // Average with rounding
PresetSummaries.countFilled();            // Count non-empty values
PresetSummaries.percentTrue();            // Percentage of true values
PresetSummaries.uniqueJoin(', ');         // Join unique values

import { createBase } from './index';

const base = createBase()
  .withFilters({ and: ['file.hasTag("task")'] })
  .addFormula('days_old', '((now() - file.ctime) / 86400000).round(0)')
  .configureProperty('status', { displayName: 'Status' })
  .addTableView('Active Tasks', {
    order: ['file.name', 'status'],
    filters: { and: ['status != "done"'] },
  })
  .addCardsView('Task Cards', {
    order: ['file.name', 'status'],
  })
  .build();

import { createFilter, and, or, not } from './index';

const filter = createFilter()
  .and('file.hasTag("project")')
  .and('file.ext == "md"')
  .not('file.hasTag("archived")')
  .build();

// Or start with a specific operator
const filter2 = and(
  'file.hasTag("important")',
  or('priority == 1', 'priority == 2')
);

import {
  createBase,
  PresetFilters,
  PresetFormulas,
  serializeToYAML,
} from './index';

const taskBase = createBase()
  .withFilters(
    and(
      PresetFilters.byTag('task'),
      PresetFilters.byExtension('md')
    )
  )
  .addFormula('days_until_due', PresetFormulas.daysUntilDue())
  .addFormula('is_overdue', PresetFormulas.isOverdue())
  .addFormula('priority_label', PresetFormulas.priorityLabel())
  .configureProperty('formula.days_until_due', { displayName: 'Days Left' })
  .addTableView('Active Tasks', {
    order: ['file.name', 'formula.priority_label', 'due'],
    filters: not(PresetFilters.byStatus('done')),
    groupBy: { property: 'status', direction: 'ASC' },
  })
  .addTableView('Completed Tasks', {
    order: ['completed_date', 'file.name'],
    filters: PresetFilters.byStatus('done'),
  })
  .build();

console.log(serializeToYAML(taskBase));

obsidian-bases-parser/
├── src/
│   ├── index.ts                    # Main exports
│   ├── obsidian-bases-schema.ts    # Type definitions
│   ├── obsidian-bases-parser.ts    # Lexer, parser, evaluator
│   ├── obsidian-bases-utils.ts     # Builders, presets, serialization
│   ├── obsidian-bases-reactive.ts  # Reactive system (Vue + ReactiveBase)
│   └── obsidian-bases-example.ts   # Usage examples
├── examples/
│   ├── reactive-base-example.ts    # Comprehensive reactive base examples
│   └── simple-reactive-demo.ts     # Simple demonstration
├── llms.txt                        # LLM overview
├── llms-full.txt                   # Complete LLM documentation
└── README.md                       # This file

import { createReactiveBase, ReactiveBaseQuery } from './index';

// Create a reactive base
const base = createReactiveBase();

// Add filters dynamically
base.addFilter('file.hasTag("task")');
base.addFilter('status != "done"');

// Add formulas
base.addFormula('days_old', '((now() - file.ctime) / 86400000).round(0)');

// Add views
base.addTableView('Active Tasks', {
  order: ['file.name', 'formula.days_old'],
  filters: 'priority > 2',
});

// Use with reactive query
const query = new ReactiveBaseQuery(source, base.ref);
const results = query.getViewResults('Active Tasks');

// Modify the base - results automatically update!
base.setViewFilters('Active Tasks', 'priority > 1');
base.addFormula('priority_label', 'if(priority == 1, "High", "Low")');
base.setViewOrder('Active Tasks', ['formula.priority_label', 'file.name']);

// Convert to YAML for saving
const yaml = base.toYAML();

import { ref } from 'vue';
import { createReactiveBase, ReactiveBaseQuery, BaseSource } from './index';

const source = ref<BaseSource[]>([/* your data */]);
const base = createReactiveBase();

// Initial setup
base.addFilter('file.hasTag("project")')
    .addTableView('Projects', { order: ['file.name'] });

// Create query
const query = new ReactiveBaseQuery(source, base.ref);
const results = query.getViewResults('Projects');

// Later: Add a new formula
base.addFormula('status_icon', 'if(status == "done", "✅", "⏳")');

// Update view to use new formula
base.setViewOrder('Projects', ['formula.status_icon', 'file.name']);

// Results automatically update with new formula and ordering!
console.log(results.value.items);

// Later: Change filters
base.clearFilters();
base.addFilter('file.hasTag("active-project")');

// Results automatically re-filter!
console.log(results.value.items);

import { createReactiveBaseFromYAML } from './index';

const yaml = `
filters:
  and:
    - file.hasTag("task")
formulas:
  days_old: '((now() - file.ctime) / 86400000).round(0)'
views:
  - type: table
    name: "Tasks"
    order:
      - file.name
`;

const base = createReactiveBaseFromYAML(yaml);

// Now modify it
base.addFormula('priority_label', 'if(priority == 1, "High", "Low")');
base.addTableView('High Priority', {
  filters: 'priority == 1',
  order: ['file.name'],
});

// Save back to YAML
const updatedYaml = base.toYAML();

import { createBase } from './index';

// Build once
const base = createBase()
  .addFilter('file.hasTag("task")')
  .addFormula('days_old', '((now() - file.ctime) / 86400000).round(0)')
  .addTableView('Tasks', { order: ['file.name'] })
  .build(); // Returns a plain object

// ❌ Cannot modify after build
// You would need to rebuild from scratch

// Use with query
const query = new ReactiveBaseQuery(source, base);

import { createReactiveBase } from './index';

// Create reactive base
const base = createReactiveBase()
  .addFilter('file.hasTag("task")')
  .addFormula('days_old', '((now() - file.ctime) / 86400000).round(0)')
  .addTableView('Tasks', { order: ['file.name'] });
// No .build() needed - stays reactive!

// ✅ Can modify anytime
base.addFormula('priority_label', 'if(priority == 1, "High", "Low")');
base.setViewOrder('Tasks', ['formula.priority_label', 'file.name']);

// Use with query - changes propagate automatically
const query = new ReactiveBaseQuery(source, base.ref);
const results = query.getViewResults('Tasks');

// Modifications automatically update results!
base.setViewFilters('Tasks', 'status != "done"');
console.log(results.value.items); // Automatically filtered!

import { ref } from 'vue';
import { readBase, useBaseQuery, BaseSource } from './index';

// Define your data type
interface Task {
  title: string;
  assignee: string;
}

// Create reactive source
const source = ref<BaseSource<Task>[]>([
  {
    id: '1',
    name: 'Task 1.md',
    basename: 'Task 1',
    tags: ['task', 'urgent'],
    properties: { status: 'todo', priority: 1 },
    data: { title: 'Complete docs', assignee: 'Alice' },
  },
  // ... more items
]);

// Read base from YAML
const yaml = `
filters:
  and:
    - file.hasTag("task")
formulas:
  priority_label: 'if(priority == 1, "🔴 High", "🟡 Medium")'
views:
  - type: table
    name: "Active Tasks"
    filters:
      and:
        - status != "done"
    order: [file.name, formula.priority_label]
`;

const base = readBase(yaml);

// Create reactive query
const { getViewResults, source: reactiveSource } = useBaseQuery(source, base);

// Get reactive results
const activeTasks = getViewResults('Active Tasks');

// Access in template or computed
// activeTasks.value.items - filtered, sorted items
// activeTasks.value.totalCount - total before limit
// activeTasks.value.groups - grouped items (if groupBy specified)
// activeTasks.value.summaries - calculated summaries

<template>
  <div>
    <h1>Tasks ({{ taskCount }})</h1>
    <ul>
      <li v-for="task in tasks" :key="task.id">
        {{ task.properties?.priority_label }} - {{ task.data?.title }}
      </li>
    </ul>
    <button @click="addTask">Add Task</button>
  </div>
</template>

<script setup lang="ts">
import { ref, computed } from 'vue';
import { useBaseView, readBase, BaseSource } from './index';

interface Task {
  title: string;
}

const source = ref<BaseSource<Task>[]>([/* ... */]);

const base = readBase(`
  formulas:
    priority_label: 'if(priority == 1, "🔴", "🟢")'
  views:
    - type: list
      name: "Tasks"
      order: [formula.priority_label]
`);

// useBaseView returns ComputedRefs that auto-update
const { items: tasks, totalCount: taskCount } = useBaseView(
  source,
  base,
  'Tasks'
);

function addTask() {
  source.value.push({
    id: String(Date.now()),
    name: 'New Task.md',
    properties: { priority: 1 },
    data: { title: 'New Task' },
  });
  // tasks and taskCount automatically update!
}
</script>

import { ref } from 'vue';
import { useBase, BaseSource } from './index';

interface Task {
  title: string;
  description: string;
}

const {
  // Base & State
  base,
  isLoaded,
  hasChanges,
  state,
  
  // Load/Save
  load,
  save,
  
  // Source Management
  source,
  addItem,
  updateItem,
  removeItem,
  
  // Query Access
  getViewResults,
  viewNames,
  
  // Shortcuts
  addView,
  addFormula,
  setFilters,
} = useBase<Task>({
  source: ref([]),
  trackChanges: true,
});

// Load from YAML
load(yamlString);

// Modify base
addFormula('priority_label', 'if(priority == 1, "High", "Low")');
addView({ type: 'table', name: 'Tasks', order: ['file.name'] });

// Add data
addItem({
  id: '1',
  name: 'Task.md',
  properties: { status: 'todo' },
  data: { title: 'My Task', description: 'Details' },
});

// Query
const tasks = getViewResults('Tasks');
console.log(tasks.value.items);

// Save
const yaml = save();

const { save, hasChanges } = useBase({
  base: yamlString,
  trackChanges: true,
});

// Implement auto-save with debouncing
let saveTimeout: NodeJS.Timeout | null = null;

watch(hasChanges, (changed) => {
  if (changed) {
    if (saveTimeout) clearTimeout(saveTimeout);
    
    saveTimeout = setTimeout(async () => {
      const yaml = save();
      await writeFile('config.base', yaml);
    }, 1000); // Save after 1s of no changes
  }
});

import { ref } from 'vue';
import { ReactiveBaseQuery, readBase, BaseSource } from './index';

const source = ref<BaseSource[]>([/* ... */]);
const base = readBase(yamlString);

// Create query instance
const query = new ReactiveBaseQuery(source, base, { debug: true });

// Get computed results for different views
const tableResults = query.getViewResults('Table View');
const cardResults = query.getViewResults('Card View');

// Access reactive data
console.log(tableResults.value.items);
console.log(tableResults.value.totalCount);
console.log(tableResults.value.summaries);

// Update source - results auto-update
query.setSource([...newItems]);

// Or update base - results auto-update
query.setBase(newBase);

// Force refresh
query.refresh();

interface BaseSource<T = void> {
  // Obsidian-specific fields (all optional)
  id?: string;
  name?: string;           // File name (e.g., "My Note.md")
  basename?: string;       // Without extension (e.g., "My Note")
  path?: string;           // Full path (e.g., "Notes/My Note.md")
  folder?: string;         // Parent folder (e.g., "Notes")
  ext?: string;            // Extension (e.g., "md")
  size?: number;           // File size in bytes
  ctime?: Date | string;   // Created time
  mtime?: Date | string;   // Modified time
  tags?: string[];         // Tags
  links?: string[];        // Internal links
  backlinks?: string[];    // Backlinks
  embeds?: string[];       // Embeds
  properties?: Record<string, unknown>;  // Frontmatter properties

  // Your custom data
  data?: T;
}

const query = new ReactiveBaseQuery(source, base, {
  customFunctions: {
    calculateScore: (priority: number, complexity: number) => {
      return priority * complexity * 10;
    },
    formatDate: (date: Date, format: string) => {
      // Your date formatting logic
      return formattedDate;
    },
  },
});