docs(examples): add metadata filter operator snippets

[moroshani]

Summary

• Add four runnable TypeScript metadata filter examples for $eq, $and, $in, and $near under examples/javascript/metadata-filters/.
• Share setup/query/cleanup logic so each operator snippet stays short and copyable.
• Add npm scripts and README commands for the new examples.

Closes #417

Verification

• npm ci
• npm run type-check
• npm run lint
• git diff --check

Notes

The examples require real MOSS_PROJECT_ID and MOSS_PROJECT_KEY credentials to run end-to-end. I verified them with the local TypeScript and ESLint checks; at runtime they create a temporary index, run one filtered query, and delete the index.

[CLAassistant]

All committers have signed the CLA.

[cubic-dev-ai]

3 issues found across 7 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="examples/javascript/metadata-filters/shared.ts">

<violation number="1" location="examples/javascript/metadata-filters/shared.ts:81">
P2: A failure during upload, build, or polling can leave the remotely initialized temporary index behind because `indexCreated` remains false until the entire multi-stage `createIndex` call resolves. Cleanup eligibility should be tracked once remote creation may have started, with a best-effort existence check/delete on failure.</violation>

<violation number="2" location="examples/javascript/metadata-filters/shared.ts:95">
P3: Results that omit optional `timeTakenInMs` print `in undefinedms`. Formatting the timing suffix conditionally keeps the runnable example's output valid for every `SearchResult`.</violation>

<violation number="3" location="examples/javascript/metadata-filters/shared.ts:104">
P2: When loading or querying fails and deletion also fails, the `finally` rejection replaces the original error, hiding the actual example failure. Preserve the primary exception while reporting the cleanup error separately.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

P2: When loading or querying fails and deletion also fails, the finally rejection replaces the original error, hiding the actual example failure. Preserve the primary exception while reporting the cleanup error separately.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At examples/javascript/metadata-filters/shared.ts, line 104:

<comment>When loading or querying fails and deletion also fails, the `finally` rejection replaces the original error, hiding the actual example failure. Preserve the primary exception while reporting the cleanup error separately.</comment>

<file context>
@@ -0,0 +1,107 @@
+  } finally {
+    if (indexCreated) {
+      console.log(`\nDeleting temporary index: ${indexName}`);
+      await client.deleteIndex(indexName);
+    }
+  }
</file context>

[cubic-dev-ai]

P2: A failure during upload, build, or polling can leave the remotely initialized temporary index behind because indexCreated remains false until the entire multi-stage createIndex call resolves. Cleanup eligibility should be tracked once remote creation may have started, with a best-effort existence check/delete on failure.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At examples/javascript/metadata-filters/shared.ts, line 81:

<comment>A failure during upload, build, or polling can leave the remotely initialized temporary index behind because `indexCreated` remains false until the entire multi-stage `createIndex` call resolves. Cleanup eligibility should be tracked once remote creation may have started, with a best-effort existence check/delete on failure.</comment>

<file context>
@@ -0,0 +1,107 @@
+
+    console.log(`\nCreating temporary index: ${indexName}`);
+    await client.createIndex(indexName, documents, { modelId: "moss-minilm" });
+    indexCreated = true;
+
+    console.log("Loading index locally for filtered query...");
</file context>

[cubic-dev-ai]

P3: Results that omit optional timeTakenInMs print in undefinedms. Formatting the timing suffix conditionally keeps the runnable example's output valid for every SearchResult.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At examples/javascript/metadata-filters/shared.ts, line 95:

<comment>Results that omit optional `timeTakenInMs` print `in undefinedms`. Formatting the timing suffix conditionally keeps the runnable example's output valid for every `SearchResult`.</comment>

<file context>
@@ -0,0 +1,107 @@
+      filter: example.filter,
+    });
+
+    console.log(`\nFound ${results.docs.length} result(s) in ${results.timeTakenInMs}ms:`);
+    results.docs.forEach((doc, index) => {
+      const preview = doc.text.length > 80 ? `${doc.text.slice(0, 80)}...` : doc.text;
</file context>

[moroshani]

Update: I was able to complete the CLA from another device. The CLA check now shows signed. Thanks.

[Copilot]

Pull request overview

Adds runnable, copy-pasteable TypeScript examples demonstrating metadata filter operators in the JavaScript examples package (examples/javascript/), aligning with the repo’s goal of providing practical SDK usage snippets.

Changes:

• Added four runnable operator-focused scripts for $eq, $and, $in, and $near under examples/javascript/metadata-filters/.
• Introduced a shared helper to centralize setup (env, temporary index creation/loading), querying, and teardown.
• Updated the JavaScript examples README and package.json scripts to make running the new samples straightforward.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
examples/javascript/README.md	Documents the new metadata filter operator samples and how to run them.
examples/javascript/package.json	Adds npm run metadata:* scripts to run each operator snippet.
examples/javascript/metadata-filters/shared.ts	Shared runner that creates a temporary index, performs a filtered query, prints results, and cleans up.
examples/javascript/metadata-filters/eq.ts	Runnable $eq filter example.
examples/javascript/metadata-filters/and.ts	Runnable $and composition example.
examples/javascript/metadata-filters/in.ts	Runnable $in filter example.
examples/javascript/metadata-filters/near.ts	Runnable $near geo-distance filter example.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

CONSIDER ```ts
await client.deleteIndex(indexName);

If create/load/query throws and `deleteIndex` also rejects, the `finally` rejection replaces the original error, so the sample reports only the cleanup failure. Preserve the primary error by catching cleanup separately, for example `try { await client.deleteIndex(indexName); } catch (cleanupError) { console.warn("Failed to delete temporary index", cleanupError); }`.

[github-actions]

Codex review

The PR adds useful metadata-filter samples, but the shared cleanup path can hide the actual failure users need to debug.