@semiont/graph 0.5.25 → 0.5.26

package/README.md

@@ -166,7 +166,7 @@ await graph.getResource(id);
 await graph.updateResource(id, updates);
 await graph.deleteResource(id);
 await graph.listResources({ entityTypes: ['Person'] });
-await graph.searchResources('query');
+await graph.listResources({ search: 'query' });
 
 // Annotation operations
 await graph.createAnnotation(input);

package/dist/index.d.ts

@@ -1,5 +1,15 @@
 import { ResourceDescriptor, ResourceId, UpdateResourceInput, ResourceFilter, CreateAnnotationInternal, Annotation, AnnotationId, AnnotationCategory, GraphConnection, GraphPath, EntityTypeStats, GraphServiceConfig, Logger } from '@semiont/core';
 
+/**
+ * Newest first, ties broken by id — the ordering every `listResources` result
+ * must carry.
+ *
+ * The tiebreak is not cosmetic: browse pages these results with offset/limit,
+ * and a partial order lets two pages repeat or drop rows. Ids compare by code
+ * point rather than locale so the JS backends agree with the engines, whose
+ * `ORDER BY` is codepoint-ordered.
+ */
+declare function compareByRecencyThenId(a: ResourceDescriptor, b: ResourceDescriptor): number;
 interface GraphDatabase {
     connect(): Promise<void>;
     disconnect(): Promise<void>;
@@ -12,7 +22,6 @@ interface GraphDatabase {
         resources: ResourceDescriptor[];
         total: number;
     }>;
-    searchResources(query: string, limit?: number): Promise<ResourceDescriptor[]>;
     createAnnotation(input: CreateAnnotationInternal): Promise<Annotation>;
     getAnnotation(id: AnnotationId): Promise<Annotation | null>;
     updateAnnotation(id: AnnotationId, updates: Partial<Annotation>): Promise<Annotation>;
@@ -102,7 +111,6 @@ declare class Neo4jGraphDatabase implements GraphDatabase {
         resources: ResourceDescriptor[];
         total: number;
     }>;
-    searchResources(query: string, limit?: number): Promise<ResourceDescriptor[]>;
     createAnnotation(input: CreateAnnotationInternal): Promise<Annotation>;
     getAnnotation(id: AnnotationId): Promise<Annotation | null>;
     updateAnnotation(id: AnnotationId, updates: Partial<Annotation>): Promise<Annotation>;
@@ -173,11 +181,28 @@ declare class NeptuneGraphDatabase implements GraphDatabase {
     getResource(id: ResourceId): Promise<ResourceDescriptor | null>;
     updateResource(id: ResourceId, input: UpdateResourceInput): Promise<ResourceDescriptor>;
     deleteResource(id: ResourceId): Promise<void>;
+    /**
+     * Filtering, ranking and pagination happen in JS rather than in Gremlin.
+     *
+     * The ranking ladder (exact name over prefix over substring over path- or
+     * tag-assisted) has no natural Gremlin expression, and a rank applied after
+     * `range()` would order one page instead of the match set. JanusGraph
+     * post-filters for the same reason. Both share `queryResources` with the
+     * memory backend so search cannot mean three different things across three
+     * backends.
+     *
+     * The cost is explicit and accepted: this materializes every `Resource`
+     * vertex per call, so it is O(N) in the size of the KB rather than in the
+     * size of the result. Neo4j is the production path and pushes the whole
+     * query — filter, rank, page — into Cypher; Neptune and JanusGraph are not
+     * deployment targets today. If either becomes one at scale, the fix is a
+     * Gremlin rank expression (`choose` over `toLower`, engine-version
+     * permitting), not a return to per-backend search semantics.
+     */
     listResources(filter: ResourceFilter): Promise<{
         resources: ResourceDescriptor[];
         total: number;
     }>;
-    searchResources(query: string, limit?: number): Promise<ResourceDescriptor[]>;
     createAnnotation(input: CreateAnnotationInternal): Promise<Annotation>;
     getAnnotation(id: AnnotationId): Promise<Annotation | null>;
     updateAnnotation(id: AnnotationId, updates: Partial<Annotation>): Promise<Annotation>;
@@ -253,7 +278,6 @@ declare class JanusGraphDatabase implements GraphDatabase {
         resources: ResourceDescriptor[];
         total: number;
     }>;
-    searchResources(query: string, limit?: number): Promise<ResourceDescriptor[]>;
     createAnnotation(input: CreateAnnotationInternal): Promise<Annotation>;
     getAnnotation(id: AnnotationId): Promise<Annotation | null>;
     updateAnnotation(id: AnnotationId, updates: Partial<Annotation>): Promise<Annotation>;
@@ -309,7 +333,6 @@ declare class MemoryGraphDatabase implements GraphDatabase {
         resources: ResourceDescriptor[];
         total: number;
     }>;
-    searchResources(query: string, limit?: number): Promise<ResourceDescriptor[]>;
     createAnnotation(input: CreateAnnotationInternal): Promise<Annotation>;
     getAnnotation(id: AnnotationId): Promise<Annotation | null>;
     updateAnnotation(id: AnnotationId, updates: Partial<Annotation>): Promise<Annotation>;
@@ -355,5 +378,5 @@ declare class MemoryGraphDatabase implements GraphDatabase {
     clearDatabase(): Promise<void>;
 }
 
-export { JanusGraphDatabase, MemoryGraphDatabase, Neo4jGraphDatabase, NeptuneGraphDatabase, closeGraphDatabase, createGraphDatabase, getGraphDatabase };
+export { JanusGraphDatabase, MemoryGraphDatabase, Neo4jGraphDatabase, NeptuneGraphDatabase, closeGraphDatabase, compareByRecencyThenId, createGraphDatabase, getGraphDatabase };
 export type { GraphDatabase };

package/dist/index.js

@@ -6,6 +6,54 @@ function assertMutableResourceUpdate(input) {
     throw new Error("Resources are immutable apart from archival state and entity tags.");
   }
 }
+function compareByRecencyThenId(a, b) {
+  const aTime = a.dateCreated ? Date.parse(a.dateCreated) : 0;
+  const bTime = b.dateCreated ? Date.parse(b.dateCreated) : 0;
+  if (aTime !== bTime) return bTime - aTime;
+  const aId = String(a["@id"]);
+  const bId = String(b["@id"]);
+  return aId < bId ? -1 : aId > bId ? 1 : 0;
+}
+
+// src/resource-query.ts
+import { getResourceEntityTypes } from "@semiont/core";
+function searchTerms(query) {
+  return query.toLowerCase().split(/\s+/).filter(Boolean);
+}
+function searchRank(resource, query) {
+  const whole = query.trim().toLowerCase();
+  const name = (resource.name ?? "").toLowerCase();
+  if (name === whole) return 0;
+  if (name.startsWith(whole)) return 1;
+  if (searchTerms(query).every((term) => name.includes(term))) return 2;
+  return 3;
+}
+function matchesSearch(resource, terms) {
+  const name = (resource.name ?? "").toLowerCase();
+  const uri = resource.storageUri?.toLowerCase() ?? "";
+  const types = getResourceEntityTypes(resource).map((t) => t.toLowerCase());
+  return terms.every((term) => name.includes(term) || uri.includes(term) || types.some((t) => t.includes(term)));
+}
+function queryResources(all, filter) {
+  let matches = all;
+  if (filter.entityTypes && filter.entityTypes.length > 0) {
+    matches = matches.filter((doc) => filter.entityTypes.some((type) => getResourceEntityTypes(doc).includes(type)));
+  }
+  const terms = filter.search ? searchTerms(filter.search) : [];
+  if (terms.length > 0) {
+    matches = matches.filter((doc) => matchesSearch(doc, terms));
+  }
+  if (filter.archived !== void 0) {
+    matches = matches.filter((doc) => (doc.archived ?? false) === filter.archived);
+  }
+  const search = terms.length > 0 ? filter.search : void 0;
+  const ordered = [...matches].sort(
+    search ? (a, b) => searchRank(a, search) - searchRank(b, search) || compareByRecencyThenId(a, b) : compareByRecencyThenId
+  );
+  const offset = filter.offset ?? 0;
+  const limit = filter.limit ?? 20;
+  return { resources: ordered.slice(offset, offset + limit), total: ordered.length };
+}
 
 // src/implementations/neptune.ts
 import { getEntityTypes } from "@semiont/ontology";
@@ -17,7 +65,6 @@ var DescribeDBClustersCommand;
 var gremlin;
 var process2;
 var TextP;
-var order;
 var cardinality;
 var __;
 async function loadDependencies() {
@@ -30,7 +77,6 @@ async function loadDependencies() {
     gremlin = await import("gremlin");
     process2 = gremlin.process;
     TextP = process2.TextP;
-    order = process2.order;
     cardinality = process2.cardinality;
     __ = process2.statics;
   }
@@ -311,52 +357,33 @@ var NeptuneGraphDatabase = class {
       throw error;
     }
   }
+  /**
+   * Filtering, ranking and pagination happen in JS rather than in Gremlin.
+   *
+   * The ranking ladder (exact name over prefix over substring over path- or
+   * tag-assisted) has no natural Gremlin expression, and a rank applied after
+   * `range()` would order one page instead of the match set. JanusGraph
+   * post-filters for the same reason. Both share `queryResources` with the
+   * memory backend so search cannot mean three different things across three
+   * backends.
+   *
+   * The cost is explicit and accepted: this materializes every `Resource`
+   * vertex per call, so it is O(N) in the size of the KB rather than in the
+   * size of the result. Neo4j is the production path and pushes the whole
+   * query — filter, rank, page — into Cypher; Neptune and JanusGraph are not
+   * deployment targets today. If either becomes one at scale, the fix is a
+   * Gremlin rank expression (`choose` over `toLower`, engine-version
+   * permitting), not a return to per-backend search semantics.
+   */
   async listResources(filter) {
     try {
-      let traversal = this.g.V().hasLabel("Resource");
-      if (filter.entityTypes && filter.entityTypes.length > 0) {
-        traversal = traversal.filter(
-          process2.statics.or(
-            ...filter.entityTypes.map(
-              (type) => process2.statics.has("entityTypes", TextP.containing(`"${type}"`))
-            )
-          )
-        );
-      }
-      if (filter.search) {
-        traversal = traversal.filter(
-          process2.statics.or(
-            process2.statics.has("name", TextP.containing(filter.search)),
-            process2.statics.has("storageUri", TextP.containing(filter.search))
-          )
-        );
-      }
-      const totalResult = await traversal.clone().count().next();
-      const total = totalResult.value || 0;
-      const offset = filter.offset || 0;
-      const limit = filter.limit || 20;
-      const results = await traversal.order().by("created", order.desc).range(offset, offset + limit).elementMap().toList();
-      const resources = results.map(vertexToResource);
-      return { resources, total };
+      const results = await this.g.V().hasLabel("Resource").elementMap().toList();
+      return queryResources(results.map(vertexToResource), filter);
     } catch (error) {
       this.logger?.error("Failed to list resources from Neptune", { error });
       throw error;
     }
   }
-  async searchResources(query, limit = 20) {
-    try {
-      const results = await this.g.V().hasLabel("Resource").filter(
-        process2.statics.or(
-          process2.statics.has("name", TextP.containing(query)),
-          process2.statics.has("storageUri", TextP.containing(query))
-        )
-      ).order().by("created", order.desc).limit(limit).elementMap().toList();
-      return results.map(vertexToResource);
-    } catch (error) {
-      this.logger?.error("Failed to search resources in Neptune", { error });
-      throw error;
-    }
-  }
   async createAnnotation(input) {
     const id = input.id;
     const annotation = {
@@ -1009,14 +1036,24 @@ var Neo4jGraphDatabase = class {
     try {
       let whereClause = "";
       const params = {};
-      const conditions = [];
+      const conditions = ["coalesce(d.stub, false) = false"];
+      if (filter.archived !== void 0) {
+        conditions.push("d.archived = $archived");
+        params.archived = filter.archived;
+      }
       if (filter.entityTypes && filter.entityTypes.length > 0) {
         conditions.push("ANY(type IN $entityTypes WHERE type IN d.entityTypes)");
         params.entityTypes = filter.entityTypes;
       }
-      if (filter.search) {
-        conditions.push('(toLower(d.name) CONTAINS toLower($search) OR toLower(coalesce(d.storageUri, "")) CONTAINS toLower($search))');
-        params.search = filter.search;
+      const terms = filter.search ? searchTerms(filter.search) : [];
+      if (terms.length > 0) {
+        conditions.push(
+          `ALL(t IN $terms WHERE toLower(d.name) CONTAINS t
+                             OR toLower(coalesce(d.storageUri, "")) CONTAINS t
+                             OR ANY(e IN coalesce(d.entityTypes, []) WHERE toLower(e) CONTAINS t))`
+        );
+        params.terms = terms;
+        params.search = filter.search.trim().toLowerCase();
       }
       if (conditions.length > 0) {
         whereClause = "WHERE " + conditions.join(" AND ");
@@ -1028,10 +1065,18 @@ var Neo4jGraphDatabase = class {
       const total = countResult.records[0].get("total").toNumber();
       params.skip = this.neo4j.int(filter.offset || 0);
       params.limit = this.neo4j.int(filter.limit || 20);
+      const rankClause = terms.length > 0 ? `WITH d, CASE
+             WHEN toLower(d.name) = $search THEN 0
+             WHEN toLower(d.name) STARTS WITH $search THEN 1
+             WHEN ALL(t IN $terms WHERE toLower(d.name) CONTAINS t) THEN 2
+             ELSE 3
+           END AS rank
+         ` : "";
+      const orderClause = terms.length > 0 ? "ORDER BY rank, d.created DESC, d.id" : "ORDER BY d.created DESC, d.id";
       const result = await session.run(
         `MATCH (d:Resource) ${whereClause}
-         RETURN d
-         ORDER BY d.updatedAt DESC
+         ${rankClause}RETURN d
+         ${orderClause}
          SKIP $skip LIMIT $limit`,
         params
       );
@@ -1041,23 +1086,6 @@ var Neo4jGraphDatabase = class {
       await session.close();
     }
   }
-  async searchResources(query, limit = 20) {
-    const session = this.getSession();
-    try {
-      const result = await session.run(
-        `MATCH (d:Resource)
-         WHERE toLower(d.name) CONTAINS toLower($query)
-            OR toLower(coalesce(d.storageUri, "")) CONTAINS toLower($query)
-         RETURN d
-         ORDER BY d.updatedAt DESC
-         LIMIT $limit`,
-        { query, limit: this.neo4j.int(limit) }
-      );
-      return result.records.map((record) => this.parseResourceNode(record.get("d")));
-    } finally {
-      await session.close();
-    }
-  }
   async createAnnotation(input) {
     const session = this.getSession();
     try {
@@ -2004,29 +2032,7 @@ var JanusGraphDatabase = class {
   }
   async listResources(filter) {
     const docs = await this.g.V().hasLabel("Resource").toList();
-    let resources = docs.map((v) => this.vertexToResource(v));
-    if (filter.search) {
-      const needle = filter.search.toLowerCase();
-      resources = resources.filter(
-        (doc) => (doc.name?.toLowerCase().includes(needle) ?? false) || (doc.storageUri?.toLowerCase().includes(needle) ?? false)
-      );
-    }
-    if (filter.entityTypes && filter.entityTypes.length > 0) {
-      resources = resources.filter(
-        (doc) => filter.entityTypes.some((type) => doc.entityTypes?.includes(type))
-      );
-    }
-    const total = resources.length;
-    const offset = filter.offset || 0;
-    const limit = filter.limit || 50;
-    return {
-      resources: resources.slice(offset, offset + limit),
-      total
-    };
-  }
-  async searchResources(query, limit) {
-    const result = await this.listResources({ search: query, limit: limit || 10 });
-    return result.resources;
+    return queryResources(docs.map((v) => this.vertexToResource(v)), filter);
   }
   async createAnnotation(input) {
     const id = input.id;
@@ -2358,7 +2364,7 @@ var JanusGraphDatabase = class {
 // src/implementations/memorygraph.ts
 import { resourceId as makeResourceId2, annotationId as makeAnnotationId4 } from "@semiont/core";
 import { v4 as uuidv44 } from "uuid";
-import { getBodySource as getBodySource4, getTargetSource as getTargetSource3, getResourceId as getResourceId3, getPrimaryRepresentation as getPrimaryRepresentation4, getResourceEntityTypes } from "@semiont/core";
+import { getBodySource as getBodySource4, getTargetSource as getTargetSource3, getResourceId as getResourceId3, getPrimaryRepresentation as getPrimaryRepresentation4, getResourceEntityTypes as getResourceEntityTypes2 } from "@semiont/core";
 var MemoryGraphDatabase = class {
   connected = false;
   logger;
@@ -2407,30 +2413,7 @@ var MemoryGraphDatabase = class {
     }
   }
   async listResources(filter) {
-    let docs = Array.from(this.resources.values());
-    if (filter.entityTypes && filter.entityTypes.length > 0) {
-      docs = docs.filter(
-        (doc) => doc.entityTypes && doc.entityTypes.some((type) => filter.entityTypes.includes(type))
-      );
-    }
-    if (filter.search) {
-      const searchLower = filter.search.toLowerCase();
-      docs = docs.filter(
-        (doc) => doc.name.toLowerCase().includes(searchLower) || (doc.storageUri?.toLowerCase().includes(searchLower) ?? false)
-      );
-    }
-    const total = docs.length;
-    const offset = filter.offset || 0;
-    const limit = filter.limit || 20;
-    docs = docs.slice(offset, offset + limit);
-    return { resources: docs, total };
-  }
-  async searchResources(query, limit = 20) {
-    const searchLower = query.toLowerCase();
-    const results = Array.from(this.resources.values()).filter(
-      (doc) => doc.name.toLowerCase().includes(searchLower) || (doc.storageUri?.toLowerCase().includes(searchLower) ?? false)
-    ).slice(0, limit);
-    return results;
+    return queryResources(Array.from(this.resources.values()), filter);
   }
   async createAnnotation(input) {
     const id = input.id;
@@ -2583,7 +2566,7 @@ var MemoryGraphDatabase = class {
   async getEntityTypeStats() {
     const typeCounts = /* @__PURE__ */ new Map();
     for (const doc of this.resources.values()) {
-      const types = getResourceEntityTypes(doc);
+      const types = getResourceEntityTypes2(doc);
       for (const type of types) {
         typeCounts.set(type, (typeCounts.get(type) || 0) + 1);
       }
@@ -2787,6 +2770,7 @@ export {
   Neo4jGraphDatabase,
   NeptuneGraphDatabase,
   closeGraphDatabase,
+  compareByRecencyThenId,
   createGraphDatabase,
   getGraphDatabase
 };