Enhanced SubjectEntity Query System

[jhweir]

Enhanced SubjectEntity Query System

This PR introduces a new, more powerful query system for SubjectEntity that enables complex queries with a fluent interface and real-time subscriptions to query results.

Key Features

1. Unified Query Building: All instance queries now use a single Prolog query that fetches all properties, collections, and metadata in one go
2. Rich Query Constraints: Support for filtering by:

• Properties and their values
• Source
• Collections
• Author and timestamp metadata

3. Result Shaping: Control over what data is returned via:

• Property selection
• Collection selection
• Ordering
• Pagination (limit/offset)

4. Real-time Query Subscriptions: Subscribe to query results and receive updates when matching instances change
   Huge for a much more performant implementation of our hooks! - coming next

5. Fluent Interface: Chain-able query building for better readability

Example usage

// Basic query with where clause
const recipes = await Recipe.findAll(perspective, { 
  where: { name: "Pancakes" } 
});

// Complex query with multiple constraints
const recipes = await Recipe.findAll(perspective, {
  where: { 
    name: "Pancakes",
    author: currentUser.did
  },
  properties: ["name", "ingredients"],
  collections: ["comments"],
  limit: 10,
  offset: 0
});

// Using the fluent query builder
const query = Recipe.query(perspective)
  .where({ name: "Pancakes" })
  .properties(["name", "ingredients"])
  .collections(["comments"])
  .limit(10);

// Run once
const results = await query.run();

// Or subscribe to updates
query.subscribeAndRun((recipes) => {
  console.log("Query results updated:", recipes);
});

Implementation Details

The new query system works by:

1. Building a comprehensive Prolog query that includes all necessary constraints
2. Executing the query to get all matching instances and their data in a single round-trip
3. Converting the Prolog results into properly typed SubjectEntity instances
4. For subscriptions, watching for changes and re-running the query automatically

This replaces the previous approach of fetching instances and their data separately, resulting in better performance and enabling more complex queries.