RFD <HydraDB>: Don't Make Users Manage Your State Machine

suggestion.md

Old

Currently, HydraDB TS SDK exposes it's API like this:

// create DB, then users manually poll until infra is ready.

await client.databases.create({ database: "acme" })

while (true) {
  const status = await client.databases.status({ database: "acme" })

  if (status.data.infra.readyForIngestion) break
  await sleep(5000)
}

// ingest content, then users manually poll indexing state.

const source = await client.context.ingest({
  database: "acme",
  content,
})

while (true) {
  const status = await client.context.status({
    database: "acme",
    sourceId: source.id,
  })

  if (status.indexingStatus === "completed") break
  await sleep(2000)
}

this sucks cause users shouldn't have to understand or reimplement HydraDb's internal async state machine just to know when a database or source is ready.

Better

// SDK owns polling, retries, timeouts, and state interpretation.

const db = await client.databases.create({ database: "acme" })
await db.ready()

const source = await client.context.ingest({
  database: "acme",
  content,
})

await source.queryable()   // normal retrieval works
await source.graphReady()  // only if full graph processing is needed

the backend can stay fully async. the improvement is just: keep low level status APIs, but move the repetitive polling/state machine logic into the SDK.

this is borrowing concepts and familiar patterns from ORMs like Drizzle, which JS ecosystem love!

// drizzle doesn't make you manage raw SQL mechanics everywhere:
await db.insert(users).values({ name: "Sree" })

// hydra shouldn't make users manage its async state machine everywhere:
const source = await hydra.context.ingest({ content })
await source.queryable()