FlashCollection API Reference

The FlashClientCollection class provides a fluent document DB interface for executing encrypted operations, queries, aggregations, and more.

---

Getting a Collection

After flashsh wrap-key in your project (recommended), or with secretKey / env:

import { FlashClient } from "flash-zk";

const client = new FlashClient({ storagePath: "./flash_data" });

// Synchronous creation/access
const collection = client.collection("collection_name");

// With schema
const users = client.collection("users", {
  schema: {
    name: { type: "string", required: true, trim: true },
    email: { type: "string", required: true, unique: true },
  },
});

---

Methods Summary

Method	Returns	Description
insertOne(doc)	Promise<{ insertedId, merkleRoot }>	Insert and encrypt a single document.
insertMany(docs)	Promise<{ insertedCount, insertedIds }>	Batch insert multiple documents.
find(filter?, options?)	FlashQuery<T>	Fluent query builder with chaining.
findOne(filter?)	Promise<T | null>	Return the first matching decrypted document.
findById(id)	Promise<T | null>	Find by document _id.
updateOne(filter, update, options?)	Promise<UpdateResult>	Update one matching document.
updateMany(filter, update, options?)	Promise<UpdateResult>	Update all matching documents.
findOneAndUpdate(filter, update, options?)	Promise<T | null>	Find and return updated document.
findByIdAndUpdate(id, update, options?)	Promise<T | null>	Find by ID, update, and return.
deleteOne(filter)	Promise<{ deletedCount }>	Delete and archive to .flash-trash for undo.
deleteMany(filter)	Promise<DeleteResult>	Delete all matching documents (each archived).
restoreOne(docId)	Promise<FlashRestoreResult>	Restore a document from trash.
listTrash(options?)	Promise<FlashTrashEntry[]>	List recoverable deletions.
purgeTrash()	Promise<{ purged: boolean }>	Clear trash for this collection's vault.
listDeletions(options?)	Promise<FlashDeletionLogEntry[]>	List permanent delete/restore log (opt-in).
bulkWrite(operations, options?)	Promise<BulkWriteResult>	Execute batch operations in one call.
aggregate(pipeline)	Promise<object[]>	Run aggregation pipeline.
count(filter?)	Promise<number>	Count documents.
createIndex(keySpec, options?)	string	Create a secondary index.
listIndexes()	IndexInfo[]	List all indexes.
dropIndex(name)	boolean	Drop an index.
watch(filter?)	FlashChangeStream	Watch for real-time change events.
vectorSearch(params)	Promise<(T & { _score: number })[]>	Semantic vector search.
verifyRecordIntegrity(docId)	Promise<MerkleProofResult>	Validate Merkle proof.
setSchema(schema, options?)	this	Set or update collection schema.
ask(prompt, options?)	Promise<(T & { _interpretedQuery? })[]>	Natural language query.
timeSeriesBucket(...)	Promise<object[]>	Time-series bucketing.
spatialNear(field, nearSpec)	Promise<object[]>	Geospatial nearest-neighbor query.
paginate(filter?, opts?)	Promise<FlashPaginationResult<T>>	Cursor-based pagination.

Low-level engine access (collection.raw)

FlashClientCollection.raw is a FlashCollection. Since v1.3.2 it stores and returns buffers:

const raw = collection.raw;
await raw.insertOne(client.encryptToBuffer({ _id: "1", name: "Ada" }));

const buffers = await raw.find({});
const doc = client.decryptFromBuffer(buffers[0]);

See Buffer Pipeline.

---

Detailed Methods

insertOne(doc)

Encrypts fields with AES-256-GCM (with AAD binding), generates HMAC Blind Index trapdoors, appends WAL frame, updates MemTable, and recalculates Merkle root.

const res = await collection.insertOne({
  title: "Quantum Computing",
  views: 1540,
  published: true,
});
// res => { insertedId: 'uuid-...', merkleRoot: '33465733...' }

insertMany(docs)

const res = await collection.insertMany([
  { title: "Post A", views: 100 },
  { title: "Post B", views: 200 },
]);
// res => { insertedCount: 2, insertedIds: ['...', '...'] }

find(filter, options)

Returns a FlashQuery with fluent chaining for sorting, pagination, selection, and more:

// All documents
const all = await collection.find();

// Fluent query with chaining
const results = await collection
  .find({ published: true })
  .sort({ views: -1 })
  .limit(10)
  .skip(5)
  .select({ title: 1, views: 1 })
  .lean();

// Field-level operators
const filtered = await collection.find({
  views: { $gte: 100, $lte: 500 },
  status: { $in: ["active", "published"] },
});

Supported filter operators: $eq, $gt, $gte, $lt, $lte, $in, $nin, $regex, $ne, $exists, $and, $or, $not, $nor, $elemMatch, $size, $all, $type, $mod.

updateOne(filter, update, options?)

const result = await collection.updateOne(
  { email: "alice@example.com" },
  { $set: { name: "Alice Updated" }, $inc: { loginCount: 1 } },
);
// result => { matchedCount: 1, modifiedCount: 1 }

// Upsert
await collection.updateOne(
  { email: "new@example.com" },
  { $setOnInsert: { name: "New User", createdAt: new Date() } },
  { upsert: true },
);

Update operators: $set, $unset, $inc, $mul, $min, $max, $push, $pull, $addToSet, $pop, $currentDate, $setOnInsert.

updateMany(filter, update, options?)

const result = await collection.updateMany(
  { status: "draft" },
  { $set: { status: "published" }, $inc: { version: 1 } },
);

findOneAndUpdate(filter, update, options?)

const doc = await collection.findOneAndUpdate(
  { email: "alice@example.com" },
  { $inc: { loginCount: 1 } },
  { new: true }, // return the updated document
);

bulkWrite(operations, options?)

Execute multiple operations in a single call:

const result = await collection.bulkWrite(
  [
    { insertOne: { document: { name: "Alice", email: "alice@x.com" } } },
    {
      updateOne: {
        filter: { email: "bob@x.com" },
        update: { $set: { active: true } },
      },
    },
    { deleteMany: { filter: { status: "archived" } } },
  ],
  { ordered: false },
);

aggregate(pipeline)

const summary = await collection.aggregate([
  { $match: { views: { $gte: 100 } } },
  {
    $group: {
      _id: "$published",
      totalViews: { $sum: "$views" },
      avgViews: { $avg: "$views" },
      articleCount: { $count: 1 },
    },
  },
  { $sort: { totalViews: -1 } },
  { $limit: 10 },
]);

Supported stages: $match, $group, $sort, $limit, $skip, $project, $addFields, $unwind, $lookup, $count, $unwind, $replaceRoot, $sample, $set, $out, $geoNear, $graphLookup.

vectorSearch(params)

Perform semantic vector search using HNSW index:

const similar = await collection.vectorSearch({
  vector: [0.1, 0.2, 0.3, ...],  // query embedding
  topK: 5,
  filter: { category: 'tech' }   // optional metadata filter
});
// Returns: [{ _id: '...', _score: 0.95, title: '...', ... }, ...]

ask(prompt, options?)

Natural language query using the AI query engine:

const results = await collection.ask(
  "show me users who signed up in the last week and have more than 100 points",
  { limit: 20 },
);

watch(filter?)

Watch for real-time change events:

const stream = collection.watch({ status: "completed" });
stream.on("change", (event) => {
  console.log(event.operationType, event.doc);
});

setSchema(schema, options?)

Set or update collection schema with optional TTL:

collection.setSchema(
  {
    name: { type: "string", required: true },
    email: { type: "string", required: true, unique: true },
  },
  { expireAfterSeconds: 86400, ttlField: "createdAt" },
);

verifyRecordIntegrity(docId)

Validates cryptographic Merkle Tree proof:

const result = await collection.verifyRecordIntegrity("doc_uuid");
if (result.isValid) {
  console.log("Record is authentic and untampered!");
}

createIndex(keySpec, options?)

collection.createIndex({ email: 1 }, { unique: true });
collection.createIndex({ createdAt: -1 });

listIndexes()

const indexes = collection.listIndexes();
// [{ name: 'email_1', spec: { email: 1 }, unique: true }, ...]