Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
use async_lock::Mutex;
use cache_core::codec::{
CACHE_FORMAT_VERSION, CACHE_SCHEMA_COMPATIBILITY_EPOCH, UNVERSIONED_STORAGE_VERSIONS,
cache_database_name, legacy_cache_database_name,
};
use cache_core::deps::OpId;
use cache_core::engine::{
BeginOptimisticWrite, CommitOptimisticWriteResult, DeferOptimisticWriteResult, Engine,
EngineError, InitialClaimOutcome, NetworkWrite, QueryRegistration, ReadResult,
RollbackOptimisticWriteResult, WriteResult,
};
use cache_core::entity_resolver::EntityResolver;
use cache_core::link_patch::{OptimisticLinkPatch, QueryRevalidation};
use cache_core::predicate::PredicateQueryResult;
use cache_core::query_inspection::QueryInspection;
use cache_core::queue::{
ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationUpsertKind,
};
use cache_core::record_selection::cache::RecordSelectionCache;
use cache_core::search::SearchRequest;
use cache_core::store::QueueDiagnosticsAvailability;
use cache_core::value::EntityKey;
use cache_turso::{
PhysicalResetReason, QueuedMutationCount, TursoStorage, TursoStorageCloseOutcome,
TursoStorageError, TursoStorageOpenOutcome, count_queued_mutations,
};
use predicate_index::RecordKey;
use serde::{Deserialize, Serialize};
use soup_filter_cache_adapter::{
SoupFilterCompileOutcome, authoritative_projection_mutations,
compile_current_filter_request as compile_filter_request, dirty_projection_mutations,
mail::ProjectionError as MailProjectionError, notification_deletion_updates,
notification_projection_updates, optimistic_notification_updates,
optimistic_projection_mutations,
};
use std::cell::RefCell;
use std::collections::HashMap;
use std::rc::Rc;
use turso_opfs::{OpenResult, OpfsError, OpfsErrorKind, OpfsOwner};
use wasm_bindgen::prelude::*;
use wasm_bindgen_futures::{JsFuture, future_to_promise};
mod calendar;
#[cfg(test)]
mod test;
#[cfg(test)]
mod test_storage;
#[cfg(test)]
use test_storage::{BrowserStorage, TestStorageFault};
/// Interns host-side string operation ids to engine `u64` ids.
#[derive(Default)]
struct OpInterner {
by_name: HashMap<String, OpId>,
by_id: HashMap<OpId, String>,
next: OpId,
}
impl OpInterner {
fn intern(&mut self, name: &str) -> OpId {
if let Some(id) = self.by_name.get(name) {
return *id;
}
self.next += 1;
let id = self.next;
self.by_name.insert(name.to_string(), id);
self.by_id.insert(id, name.to_string());
id
}
fn remove(&mut self, name: &str) -> Option<OpId> {
let id = self.by_name.remove(name)?;
self.by_id.remove(&id);
Some(id)
}
fn names(&self, ids: impl IntoIterator<Item = OpId>) -> Vec<String> {
ids.into_iter()
.filter_map(|id| self.by_id.get(&id).cloned())
.collect()
}
}
#[derive(Serialize)]
#[serde(tag = "kind", rename_all = "camelCase")]
enum JsReadResult {
Hit { data: serde_json::Value },
Miss,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum CacheOpenOutcome {
OpenedExisting,
OpenedNew,
ResetIncompatible,
ResetCorrupt,
ResetStorageUncertain,
}
impl CacheOpenOutcome {
const fn as_str(self) -> &'static str {
match self {
Self::OpenedExisting => "opened-existing",
Self::OpenedNew => "opened-new",
Self::ResetIncompatible => "reset-incompatible",
Self::ResetCorrupt => "reset-corrupt",
Self::ResetStorageUncertain => "reset-storage-uncertain",
}
}
}
impl From<TursoStorageOpenOutcome> for CacheOpenOutcome {
fn from(outcome: TursoStorageOpenOutcome) -> Self {
match outcome {
TursoStorageOpenOutcome::OpenedExisting => Self::OpenedExisting,
TursoStorageOpenOutcome::OpenedNew => Self::OpenedNew,
}
}
}
fn recovery_outcome(reason: PhysicalResetReason) -> CacheOpenOutcome {
match reason {
PhysicalResetReason::Compatibility => CacheOpenOutcome::ResetIncompatible,
PhysicalResetReason::Corruption
| PhysicalResetReason::Codec
| PhysicalResetReason::Invariant
| PhysicalResetReason::Integrity => CacheOpenOutcome::ResetCorrupt,
PhysicalResetReason::StorageFull
| PhysicalResetReason::TransactionOutcomeUncertain
| PhysicalResetReason::Io => CacheOpenOutcome::ResetStorageUncertain,
}
}
#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct JsWriteContext {
origin_op_id: Option<String>,
registration: Option<JsQueryRegistration>,
}
#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct JsQueryRegistration {
op_id: String,
#[serde(default)]
entity_resolvers: Vec<EntityResolver>,
}
#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct JsWriteResult {
#[serde(skip_serializing_if = "Option::is_none")]
unchanged_views: Option<Vec<String>>,
#[serde(skip_serializing_if = "Option::is_none")]
field_changes: Option<Vec<cache_core::field_changes::RecordFieldChange>>,
#[serde(skip_serializing_if = "Vec::is_empty")]
identity_errors: Vec<String>,
revision: String,
revision_advanced: bool,
#[serde(skip_serializing_if = "Option::is_none")]
search_changed_buckets: Option<std::collections::BTreeSet<String>>,
changed: Vec<String>,
affected_ops: Vec<String>,
reset: bool,
revalidations: Vec<QueryRevalidation>,
#[serde(skip_serializing_if = "Option::is_none")]
mutation_uuid: Option<String>,
}
#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct JsHydrationWriteResult {
unchanged_views: Vec<String>,
search_changed_buckets: std::collections::BTreeSet<String>,
revision: String,
revision_advanced: bool,
changed: Vec<String>,
affected_ops: Vec<String>,
reset: bool,
revalidations: Vec<QueryRevalidation>,
#[serde(skip_serializing_if = "Option::is_none")]
mutation_uuid: Option<String>,
data: Option<serde_json::Value>,
}
#[derive(Deserialize)]
struct JsInspectionPathSegment {
field: String,
}
#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct JsEnqueueOptimisticMutationResult {
#[serde(skip_serializing_if = "Option::is_none")]
field_changes: Option<Vec<cache_core::field_changes::RecordFieldChange>>,
transaction_id: String,
upsert_kind: JsMutationUpsertKind,
revision: String,
revision_advanced: bool,
changed: Vec<String>,
affected_ops: Vec<String>,
reset: bool,
revalidations: Vec<QueryRevalidation>,
#[serde(skip_serializing_if = "Option::is_none")]
mutation_uuid: Option<String>,
initial_claim: JsInitialMutationClaim,
}
#[derive(Serialize)]
#[serde(
tag = "kind",
rename_all = "kebab-case",
rename_all_fields = "camelCase"
)]
enum JsMutationUpsertKind {
Inserted,
ReplacedPending { removed_transaction_id: String },
AppendedAfterActive { active_transaction_id: String },
}
impl From<MutationUpsertKind> for JsMutationUpsertKind {
fn from(kind: MutationUpsertKind) -> Self {
match kind {
MutationUpsertKind::Inserted => Self::Inserted,
MutationUpsertKind::ReplacedPending { removed_id } => Self::ReplacedPending {
removed_transaction_id: removed_id.to_string(),
},
MutationUpsertKind::AppendedAfterActive { active_id } => Self::AppendedAfterActive {
active_transaction_id: active_id.to_string(),
},
}
}
}
#[derive(Serialize)]
#[serde(tag = "kind", rename_all = "kebab-case")]
enum JsInitialMutationClaim {
Claimed { mutation: JsClaimedMutation },
NotRunnable,
Failed { error: String },
}
#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct JsClaimedMutation {
client_metadata: Option<serde_json::Value>,
transaction_id: String,
uuid: String,
superseded: bool,
requires_confirmation: bool,
lease_generation: String,
query: String,
operation_name: Option<String>,
variables: serde_json::Value,
identity: Option<String>,
attempt_count: u32,
server_failure_count: u32,
#[serde(skip_serializing_if = "Option::is_none")]
enqueued_at_ms: Option<i64>,
}
impl TryFrom<ClaimedMutation> for JsClaimedMutation {
type Error = JsValue;
fn try_from(claimed: ClaimedMutation) -> Result<Self, Self::Error> {
let requires_confirmation = claimed.queued.requires_confirmation();
let client_metadata = cache_core::queue::decode_optimistic_source(
&claimed.queued.optimistic.optimistic_data_json,
)
.map_err(err_js)?
.client_metadata;
let enqueued_at_ms = claimed.queued.mutation.enqueued_at_ms();
let request = claimed.queued.mutation.request;
Ok(Self {
client_metadata,
transaction_id: claimed.queued.id.to_string(),
uuid: claimed.queued.uuid.to_string(),
superseded: claimed.queued.superseded,
requires_confirmation,
lease_generation: claimed.lease_generation.to_string(),
query: request.query,
operation_name: request.operation_name,
variables: serde_json::from_str(&request.variables_json).map_err(err_js)?,
identity: request.identity,
attempt_count: claimed.queued.mutation.attempt_count,
server_failure_count: claimed.queued.mutation.server_failure_count,
enqueued_at_ms,
})
}
}
/// Queue ids and lease generations cross the boundary as strings because JS
/// numbers lose precision past 2^53.
fn parse_u64(value: &str, label: &str) -> Result<u64, JsValue> {
value
.parse::<u64>()
.map_err(|_| err_js(format!("invalid {label} `{value}`")))
}
fn parse_transaction_id(id: &str) -> Result<u64, JsValue> {
parse_u64(id, "optimistic transaction id")
}
fn parse_timestamp(value: f64, label: &str) -> Result<i64, JsValue> {
if !value.is_finite()
|| value.fract() != 0.0
|| value < i64::MIN as f64
|| value >= i64::MAX as f64
{
return Err(err_js(format!("invalid {label} `{value}`")));
}
Ok(value as i64)
}
#[cfg(not(test))]
type BrowserStorage = TursoStorage;
type BrowserEngine = Engine<BrowserStorage>;
#[cfg(not(test))]
fn wrap_storage(storage: TursoStorage) -> BrowserStorage {
storage
}
#[cfg(test)]
fn wrap_storage(storage: TursoStorage) -> BrowserStorage {
BrowserStorage::new(storage)
}
#[cfg(not(test))]
fn unwrap_storage(storage: BrowserStorage) -> TursoStorage {
storage
}
#[cfg(test)]
fn unwrap_storage(storage: BrowserStorage) -> TursoStorage {
storage.into_inner()
}
#[derive(Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
struct JsEntityFilterRequest {
live_query: Option<soup_filter_cache_adapter::live_query::LiveQueryRequest>,
filters: serde_json::Value,
sort_method: String,
sort_direction: String,
limit: u16,
baseline: Option<Vec<JsPredicateBaselineEntry>>,
mail: Option<soup_filter_cache_adapter::mail::PageRequest>,
}
#[derive(Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
struct JsPredicateBaselineEntry {
key: String,
sort_timestamp: String,
}
#[derive(Serialize)]
#[serde(tag = "kind", rename_all = "kebab-case")]
enum JsEntityFilterResult {
LiveQuery {
#[serde(flatten)]
update: cache_core::engine::live_query::LiveQueryUpdate,
},
Reconciled {
revision: String,
keys: Vec<String>,
#[serde(rename = "retainedKeys")]
retained_keys: Vec<String>,
optimistic: bool,
},
Complete {
revision: String,
keys: Vec<String>,
optimistic: bool,
},
Unsupported,
Incomplete {
revision: String,
},
}
#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct JsRecordSelectionResult {
revision: String,
records: Vec<cache_core::record_selection::SelectedRecord>,
}
#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct JsAffectedOperationsResult {
revision: String,
affected_ops: Vec<String>,
}
#[derive(Serialize)]
struct JsRevisionResult {
revision: String,
}
#[derive(Serialize)]
#[serde(
tag = "kind",
rename_all = "kebab-case",
rename_all_fields = "camelCase"
)]
enum JsDeferOptimisticWriteResult {
Deferred,
DiscardedSuperseded {
replacement_transaction_id: String,
#[serde(flatten)]
result: JsWriteResult,
},
}
#[derive(Serialize)]
#[serde(
tag = "kind",
rename_all = "kebab-case",
rename_all_fields = "camelCase"
)]
enum JsCommitOptimisticWriteResult {
Failed {
error: String,
#[serde(skip_serializing_if = "Option::is_none")]
replacement_transaction_id: Option<String>,
#[serde(flatten)]
result: JsWriteResult,
},
Committed {
#[serde(flatten)]
result: JsWriteResult,
},
CommittedSuperseded {
replacement_transaction_id: String,
#[serde(flatten)]
result: JsWriteResult,
},
}
#[derive(Serialize)]
#[serde(
tag = "kind",
rename_all = "kebab-case",
rename_all_fields = "camelCase"
)]
enum JsRollbackOptimisticWriteResult {
RolledBack {
#[serde(flatten)]
result: JsWriteResult,
},
DiscardedSuperseded {
replacement_transaction_id: String,
#[serde(flatten)]
result: JsWriteResult,
},
}
fn js_write_result(result: WriteResult, ops: &OpInterner) -> JsWriteResult {
JsWriteResult {
unchanged_views: None,
field_changes: result.field_changes,
identity_errors: result.identity_errors,
revision: result.revision.to_string(),
revision_advanced: result.revision_advanced,
search_changed_buckets: result.search_changed_buckets,
changed: result
.changed
.into_iter()
.map(|key| key.0.into_owned())
.collect(),
affected_ops: ops.names(result.affected_ops),
reset: result.reset,
revalidations: result.revalidations,
mutation_uuid: result.mutation_uuid,
}
}
struct CacheState {
selections: RecordSelectionCache,
engine: Option<BrowserEngine>,
mail_generation: String,
scope: String,
hot_capacity: Option<u32>,
reset_required: bool,
}
impl CacheState {
fn ensure_callable(&self) -> Result<(), JsValue> {
if self.reset_required {
Err(reset_required_js_error())
} else if self.engine.is_none() {
Err(closed_js_error())
} else {
Ok(())
}
}
fn engine_mut(&mut self) -> Result<&mut BrowserEngine, JsValue> {
self.ensure_callable()?;
Ok(self
.engine
.as_mut()
.expect("callable cache state contains an engine"))
}
/// Keep stored projection inputs out of writes that will reset the cache.
/// The engine still owns the identity reset and operation invalidation.
async fn can_reuse_stored_identity(&mut self, identity: Option<&str>) -> Result<bool, JsValue> {
let Some(observed) = identity else {
return Ok(true);
};
let result = self.engine_mut()?.current_identity().await;
let bound = self.engine_result(result)?;
Ok(bound.as_deref().is_none_or(|bound| bound == observed))
}
fn engine_result<T>(
&mut self,
result: Result<T, EngineError<TursoStorageError>>,
) -> Result<T, JsValue> {
result.map_err(|error| self.engine_error(error))
}
fn mail_projection_error(&mut self, error: MailProjectionError<TursoStorageError>) -> JsValue {
match error {
MailProjectionError::Storage(error) => self.engine_error(EngineError::Storage(error)),
MailProjectionError::Adapter(error) => err_js(error),
}
}
fn engine_error(&mut self, error: EngineError<TursoStorageError>) -> JsValue {
if engine_error_requires_reset(&error) {
self.reset_required = true;
reset_required_js_error()
} else {
err_js(error)
}
}
}
#[wasm_bindgen]
pub struct CacheEngine {
state: Rc<Mutex<CacheState>>,
ops: Rc<RefCell<OpInterner>>,
}
fn database_identity(scope: &str) -> String {
cache_database_name(scope, cache_turso::STORAGE_SCHEMA_VERSION)
}
/// Whether `identity` names one of this scope's databases that this build does
/// not open and that no newer build could want: the unversioned name once this
/// build's versions have moved past it, or another name for versions no newer
/// than this build's. A newer version belongs to a build that may come back,
/// for example after a rollback, so it is never stale.
fn is_stale_identity(scope: &str, identity: &str) -> bool {
let unversioned = legacy_cache_database_name(scope);
let version = if identity == unversioned {
Some(UNVERSIONED_STORAGE_VERSIONS)
} else {
storage_version(&unversioned, identity)
};
let own = (
CACHE_SCHEMA_COMPATIBILITY_EPOCH,
CACHE_FORMAT_VERSION,
cache_turso::STORAGE_SCHEMA_VERSION,
);
identity != database_identity(scope) && version.is_some_and(|version| version <= own)
}
/// The `(epoch, format, storage)` versions embedded in a scope's database name.
fn storage_version(unversioned: &str, identity: &str) -> Option<(u32, u32, u32)> {
let mut parts = identity
.strip_prefix(unversioned)?
.strip_prefix(":s")?
.split('.');
let number = |part: &str| -> Option<u32> {
if part.is_empty() || !part.bytes().all(|byte| byte.is_ascii_digit()) {
return None;
}
part.parse().ok()
};
let epoch = number(parts.next()?)?;
let format = number(parts.next()?.strip_prefix('v')?)?;
let storage = number(parts.next()?.strip_prefix('t')?)?;
parts.next().is_none().then_some((epoch, format, storage))
}
thread_local! {
static RUNTIME_SCHEMA: std::cell::RefCell<Option<std::sync::Arc<cache_core::meta::Schema>>> = const { std::cell::RefCell::new(None) };
}
/// Parses bundle SDL once per worker, before opening its engine.
#[wasm_bindgen(js_name = configureCacheSchema)]
pub fn configure_cache_schema(schema_sdl: &str) -> Result<(), JsValue> {
let schema = cache_core::meta::Schema::from_sdl(schema_sdl).map_err(err_js)?;
RUNTIME_SCHEMA.with(|slot| {
let mut slot = slot.borrow_mut();
if let Some(existing) = slot.as_ref() {
if existing.hash() != schema.hash() {
return Err(err_js("schema changed within a running cache worker"));
}
} else {
*slot = Some(schema);
}
Ok(())
})
}
fn build_engine(storage: TursoStorage, hot_capacity: Option<u32>) -> BrowserEngine {
let storage = wrap_storage(storage);
let schema = RUNTIME_SCHEMA.with(|slot| {
slot.borrow_mut()
.get_or_insert_with(cache_core::meta::bundled_schema)
.clone()
});
Engine::with_schema(
storage,
hot_capacity.map_or(cache_core::engine::DEFAULT_HOT_CAPACITY, |c| c as usize),
schema,
)
}
fn validate_hot_capacity(hot_capacity: Option<u32>) -> Result<(), JsValue> {
if hot_capacity == Some(0) {
Err(err_js("hot capacity must be greater than zero"))
} else {
Ok(())
}
}
async fn open_owner(owner: OpfsOwner) -> Result<OpenResult, JsValue> {
match owner.open().await {
Ok(opened) => Ok(opened),
Err(failure) => {
let error = storage_err_js(failure.error());
if let Some(owner) = failure.into_owner() {
owner.release().await.map_err(err_js)?;
}
Err(error)
}
}
}
struct OpenedStorage {
storage: TursoStorage,
outcome: CacheOpenOutcome,
}
async fn open_storage(scope: &str, owner: OpfsOwner) -> Result<OpenedStorage, JsValue> {
let (owner, reset_outcome) = match open_owner(owner).await? {
OpenResult::Ready(session) => {
let connected = session.connect().map_err(err_js)?;
match TursoStorage::from_opfs_session_with_outcome(connected, scope) {
Ok((storage, outcome)) => {
return Ok(OpenedStorage {
storage,
outcome: outcome.into(),
});
}
Err(failure) => {
let error = failure.error();
if !error.requires_physical_reset() {
let owner = failure.preserve().map_err(err_js)?;
owner.release().await.map_err(err_js)?;
return Err(err_js(error));
}
let outcome = recovery_outcome(
error
.physical_reset_reason()
.expect("reset-required error has a reset reason"),
);
(
failure
.reset()
.await
.map_err(|failure| storage_err_js(failure.error()))?,
outcome,
)
}
}
}
OpenResult::ResetRequired(session) => (
session
.reset()
.await
.map_err(|failure| storage_err_js(failure.error()))?,
CacheOpenOutcome::ResetStorageUncertain,
),
};
match open_owner(owner).await? {
OpenResult::Ready(session) => {
let connected = session.connect().map_err(err_js)?;
match TursoStorage::from_opfs_session(connected, scope) {
Ok(storage) => Ok(OpenedStorage {
storage,
outcome: reset_outcome,
}),
Err(failure) => {
let reset_required = failure.error().requires_physical_reset();
let owner = failure
.reset()
.await
.map_err(|failure| storage_err_js(failure.error()))?;
owner.release().await.map_err(err_js)?;
Err(if reset_required {
reset_required_js_error()
} else {
err_js("cache storage initialization failed")
})
}
}
}
OpenResult::ResetRequired(session) => {
let owner = session
.reset()
.await
.map_err(|failure| storage_err_js(failure.error()))?;
owner.release().await.map_err(err_js)?;
Err(reset_required_js_error())
}
}
}
/// Waits until the caller may touch storage while this owner holds the lock.
/// Holding the lock only proves no other engine uses the files; the browser
/// coordinator must also record that this engine's epoch may change them.
async fn await_storage_grant(
owner: OpfsOwner,
grant: &js_sys::Function,
) -> Result<OpfsOwner, JsValue> {
let granted = match grant.call0(&JsValue::UNDEFINED) {
Ok(value) => JsFuture::from(js_sys::Promise::resolve(&value)).await,
Err(error) => Err(error),
};
match granted {
Ok(_) => Ok(owner),
Err(error) => {
owner.release().await.map_err(err_js)?;
Err(error)
}
}
}
async fn acquire_storage(
scope: &str,
recovery_wipe: bool,
storage_grant: Option<&js_sys::Function>,
if_available: bool,
) -> Result<OpenedStorage, JsValue> {
let identity = database_identity(scope);
let owner = if if_available {
OpfsOwner::try_acquire(&identity)
.await
.map_err(err_js)?
.ok_or_else(owner_lock_unavailable_js_error)?
} else {
OpfsOwner::acquire(&identity).await.map_err(err_js)?
};
let owner = match storage_grant {
Some(grant) => await_storage_grant(owner, grant).await?,
None => owner,
};
let owner = if recovery_wipe {
owner
.recovery_wipe()
.await
.map_err(|failure| storage_err_js(failure.error()))?
} else {
owner
};
let mut opened = open_storage(scope, owner).await?;
if recovery_wipe {
opened.outcome = CacheOpenOutcome::ResetStorageUncertain;
}
Ok(opened)
}
async fn open_cache_inner(
scope: String,
hot_capacity: Option<u32>,
recovery_wipe: bool,
storage_grant: Option<js_sys::Function>,
if_available: bool,
) -> Result<(CacheEngine, CacheOpenOutcome), JsValue> {
validate_hot_capacity(hot_capacity)?;
let OpenedStorage { storage, outcome } =
acquire_storage(&scope, recovery_wipe, storage_grant.as_ref(), if_available).await?;
Ok((
CacheEngine {
state: Rc::new(Mutex::new(CacheState {
selections: RecordSelectionCache::default(),
engine: Some(build_engine(storage, hot_capacity)),
mail_generation: soup_filter_cache_adapter::mail::new_generation(),
scope,
hot_capacity,
reset_required: false,
})),
ops: Rc::new(RefCell::new(OpInterner::default())),
},
outcome,
))
}
fn cache_open_result(engine: CacheEngine, outcome: CacheOpenOutcome) -> Result<JsValue, JsValue> {
let result = js_sys::Object::new();
js_sys::Reflect::set(
&result,
&JsValue::from_str("engine"),
&JsValue::from(engine),
)?;
js_sys::Reflect::set(
&result,
&JsValue::from_str("outcome"),
&JsValue::from_str(outcome.as_str()),
)?;
Ok(result.into())
}
/// Opens (or creates) the cache for `scope` after acquiring its exclusive OPFS
/// owner lock. The physical identity is derived from `scope` alone; disposable
/// incomplete or incompatible files are reset and reopened before returning.
#[wasm_bindgen(js_name = openCache)]
pub async fn open_cache(scope: String, hot_capacity: Option<u32>) -> Result<CacheEngine, JsValue> {
open_cache_inner(scope, hot_capacity, false, None, false)
.await
.map(|(engine, _)| engine)
}
/// Additive open API returning the engine and payload-free recovery outcome.
///
/// When given, `on_owner_lock_acquired` is called once the owner lock is held
/// and before any OPFS access; opening continues after its promise resolves.
/// A rejection releases the lock without touching storage.
///
/// With `if_available`, opening never waits behind another holder of the
/// owner lock: it rejects at once, touching nothing, with an error whose
/// `cacheOwnerLockUnavailable` property is `true`.
///
/// When another context keeps the database files open through the adapter's
/// bounded wait, opening rejects with an error whose `cacheStorageBusy`
/// property is `true`. A plain open has then changed neither file; a recovery
/// wipe may have removed one of them.
#[wasm_bindgen(js_name = openCacheWithOutcome)]
pub async fn open_cache_with_outcome(
scope: String,
hot_capacity: Option<u32>,
on_owner_lock_acquired: Option<js_sys::Function>,
if_available: Option<bool>,
) -> Result<JsValue, JsValue> {
let (engine, outcome) = open_cache_inner(
scope,
hot_capacity,
false,
on_owner_lock_acquired,
if_available.unwrap_or(false),
)
.await?;
cache_open_result(engine, outcome)
}
/// Acquires the canonical owner once, recovery-wipes before any Turso open,
/// then opens a fresh cache while continuously retaining that same owner lock.
#[wasm_bindgen(js_name = openCacheForRecovery)]
pub async fn open_cache_for_recovery(
scope: String,
hot_capacity: Option<u32>,
) -> Result<CacheEngine, JsValue> {
open_cache_inner(scope, hot_capacity, true, None, false)
.await
.map(|(engine, _)| engine)
}
/// Additive recovery-open API returning the engine and coarse wipe outcome.
/// `on_owner_lock_acquired` and `if_available` behave as in
/// [`openCacheWithOutcome`](open_cache_with_outcome); both precede the wipe.
#[wasm_bindgen(js_name = openCacheForRecoveryWithOutcome)]
pub async fn open_cache_for_recovery_with_outcome(
scope: String,
hot_capacity: Option<u32>,
on_owner_lock_acquired: Option<js_sys::Function>,
if_available: Option<bool>,
) -> Result<JsValue, JsValue> {
let (engine, outcome) = open_cache_inner(
scope,
hot_capacity,
true,
on_owner_lock_acquired,
if_available.unwrap_or(false),
)
.await?;
cache_open_result(engine, outcome)
}
/// Physical database identity this build opens for `scope`; it also names the
/// OPFS files and derives the owner Web Lock name.
#[wasm_bindgen(js_name = cacheDatabaseIdentity)]
pub fn cache_database_identity(scope: String) -> String {
database_identity(&scope)
}
#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct StaleDatabaseCleanup {
outcome: &'static str,
#[serde(skip_serializing_if = "Option::is_none")]
queued_mutations: Option<u64>,
}
/// Deletes one of this scope's databases that an older build left behind (see
/// [`cacheDatabaseIdentity`](cache_database_identity)), unless another context
/// holds its owner lock (`in-use`) or it still queues mutations
/// (`queued-mutations`). Never waits for the lock. A file Turso cannot read,
/// or whose queue cannot be counted, is kept and rejects; the caller should
/// use a disposable worker, because such a failure can poison the
/// worker-local OPFS registry.
#[wasm_bindgen(js_name = removeStaleCacheDatabase)]
pub async fn remove_stale_cache_database(
scope: String,
identity: String,
) -> Result<JsValue, JsValue> {
if !is_stale_identity(&scope, &identity) {
return Err(err_js("not a stale cache database for this scope"));
}
let Some(owner) = OpfsOwner::try_acquire(&identity).await.map_err(err_js)? else {
return to_js(&StaleDatabaseCleanup {
outcome: "in-use",
queued_mutations: None,
});
};
let owner = match open_owner(owner).await? {
OpenResult::Ready(session) => {
let connected = session.connect().map_err(err_js)?;
let counted = count_queued_mutations(&connected);
let owner = connected
.try_close()
.map_err(err_js)?
.preserve()
.map_err(err_js)?;
match counted {
Ok(QueuedMutationCount::Queued(queued)) if queued > 0 => {
owner.release().await.map_err(err_js)?;
return to_js(&StaleDatabaseCleanup {
outcome: "queued-mutations",
queued_mutations: Some(queued),
});
}
// A queue that cannot be counted may still hold work, so the
// file is kept and the cleanup rejects as for an unreadable file.
Err(error) => {
owner.release().await.map_err(err_js)?;
return Err(err_js(error));
}
// An empty queue or no queue holds no work any build could send.
Ok(_) => owner,
}
}
// Only one of the pair exists, so it never held a complete database.
OpenResult::ResetRequired(session) => session.reset().await.map_err(err_js)?,
};
owner.remove_and_release().await.map_err(err_js)?;
to_js(&StaleDatabaseCleanup {
outcome: "removed",
queued_mutations: None,
})
}
/// Recovery-wipes and recreates the cache database for `scope` while holding
/// the same exclusive OPFS owner lock used by [`openCache`](open_cache).
#[wasm_bindgen(js_name = destroyCache)]
pub async fn destroy_cache(scope: String) -> Result<(), JsValue> {
OpfsOwner::acquire(&database_identity(&scope))
.await
.map_err(err_js)?
.recovery_wipe()
.await
.map_err(err_js)?
.release()
.await
.map_err(err_js)
}
#[cfg(feature = "browser-test-hooks")]
enum BrowserTestStorageMutation {
IncompatibleNamespace,
CorruptQueuePayload,
}
#[cfg(feature = "browser-test-hooks")]
async fn browser_test_mutate_closed_storage(
scope: String,
mutation: BrowserTestStorageMutation,
) -> Result<(), JsValue> {
let owner = OpfsOwner::acquire(&database_identity(&scope))
.await
.map_err(err_js)?;
let session = match open_owner(owner).await? {
OpenResult::Ready(session) => session,
OpenResult::ResetRequired(session) => {
let owner = session.reset().await.map_err(err_js)?;
owner.release().await.map_err(err_js)?;
return Err(err_js("browser-test storage was already reset-required"));
}
};
let connected = session.connect().map_err(err_js)?;
let mut storage = match TursoStorage::from_opfs_session(connected, &scope) {
Ok(storage) => storage,
Err(failure) => {
let owner = failure.reset().await.map_err(err_js)?;
owner.release().await.map_err(err_js)?;
return Err(err_js("browser-test storage validation failed"));
}
};
match mutation {
BrowserTestStorageMutation::IncompatibleNamespace => {
storage.browser_test_make_namespace_incompatible()
}
BrowserTestStorageMutation::CorruptQueuePayload => {
storage.browser_test_corrupt_queue_payload()
}
}
.map_err(err_js)?;
match storage.try_close().map_err(err_js)? {
TursoStorageCloseOutcome::Healthy(closed) => closed
.preserve()
.map_err(err_js)?
.release()
.await
.map_err(err_js),
TursoStorageCloseOutcome::ResetRequired(closed) => {
let owner = closed.reset().await.map_err(err_js)?;
owner.release().await.map_err(err_js)?;
Err(err_js("browser-test mutation unexpectedly required reset"))
}
}
}
/// Test-artifact-only incompatible-namespace hook.
#[cfg(feature = "browser-test-hooks")]
#[wasm_bindgen(js_name = browserTestMakeNamespaceIncompatible)]
pub async fn browser_test_make_namespace_incompatible(scope: String) -> Result<(), JsValue> {
browser_test_mutate_closed_storage(scope, BrowserTestStorageMutation::IncompatibleNamespace)
.await
}
/// Test-artifact-only corrupt-queue hook.
#[cfg(feature = "browser-test-hooks")]
#[wasm_bindgen(js_name = browserTestCorruptQueuePayload)]
pub async fn browser_test_corrupt_queue_payload(scope: String) -> Result<(), JsValue> {
browser_test_mutate_closed_storage(scope, BrowserTestStorageMutation::CorruptQueuePayload).await
}
/// Schema hash baked into this build (build diagnostics).
#[wasm_bindgen(js_name = schemaHash)]
pub fn schema_hash() -> String {
cache_core::meta::SCHEMA_HASH.to_string()
}
#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct CacheBuildInfo {
package_version: &'static str,
schema_hash: &'static str,
schema_compatibility_epoch: u32,
format_version: u32,
storage_schema_version: u32,
}
/// Read-only metadata embedded in this WASM binary, available without opening storage.
/// Recovery fixtures compare both artifacts before invoking any destructive hook.
#[wasm_bindgen(js_name = cacheBuildInfo)]
pub fn cache_build_info() -> Result<JsValue, JsValue> {
to_js(&CacheBuildInfo {
package_version: env!("CARGO_PKG_VERSION"),
schema_hash: cache_core::meta::SCHEMA_HASH,
schema_compatibility_epoch: cache_core::codec::CACHE_SCHEMA_COMPATIBILITY_EPOCH,
format_version: cache_core::codec::CACHE_FORMAT_VERSION,
storage_schema_version: cache_turso::STORAGE_SCHEMA_VERSION,
})
}
fn to_js<T: Serialize>(value: &T) -> Result<JsValue, JsValue> {
value
.serialize(&serde_wasm_bindgen::Serializer::json_compatible())
.map_err(|e| JsValue::from_str(&e.to_string()))
}
/// Read envelopes contain strings and JSON values. Converting the JSON in one
/// call avoids a Wasm/JS crossing for every nested field and array element.
fn read_response_to_js<'a, T: Serialize>(
response: &T,
values: impl IntoIterator<Item = &'a serde_json::Value>,
) -> Result<JsValue, JsValue> {
// Preserve the existing rejection of integer values outside JS's safe
// range. JSON.parse would otherwise silently round them. Floating-point
// values already have JS Number semantics and are allowed at any magnitude.
if values.into_iter().any(has_unsafe_json_integer) {
return to_js(response);
}
let json = serde_json::to_string(response).map_err(err_js)?;
js_sys::JSON::parse(&json)
}
/// JSON values a watch update sends to JS. Patch values cross the boundary
/// the same way as a hit's data, so they need the same integer check.
fn query_update_values(
update: &cache_core::engine::watch_query::QueryUpdate,
) -> Vec<&serde_json::Value> {
use cache_core::engine::watch_query::QueryUpdate;
match update {
QueryUpdate::Hit { data, .. } => vec![data.as_ref()],
QueryUpdate::Patch { patches, .. } => patches.iter().map(|patch| &patch.value).collect(),
QueryUpdate::Miss { .. } => Vec::new(),
}
}
fn has_unsafe_json_integer(value: &serde_json::Value) -> bool {
const MAX_SAFE_INTEGER: i64 = 9_007_199_254_740_991;
match value {
serde_json::Value::Number(number) => {
!number.is_f64()
&& number
.as_i64()
.is_none_or(|n| !(-MAX_SAFE_INTEGER..=MAX_SAFE_INTEGER).contains(&n))
}
serde_json::Value::Array(values) => values.iter().any(has_unsafe_json_integer),
serde_json::Value::Object(values) => values.values().any(has_unsafe_json_integer),
_ => false,
}
}
const RESET_REQUIRED_MARKER: &str = "cacheStorageResetRequired";
const RESET_REQUIRED_MESSAGE: &str = "cache storage reset required";
const OWNER_LOCK_UNAVAILABLE_MARKER: &str = "cacheOwnerLockUnavailable";
const STORAGE_BUSY_MARKER: &str = "cacheStorageBusy";
const OWNER_LOCK_UNAVAILABLE_MESSAGE: &str = "cache database owner lock is held by another context";
/// All rejections surface as real `Error` objects with consistent
/// `instanceof Error` and `.message` behavior.
fn err_js(error: impl std::fmt::Display) -> JsValue {
js_sys::Error::new(&error.to_string()).into()
}
fn closed_js_error() -> JsValue {
err_js("cache engine is closed")
}
fn reset_required_js_error() -> JsValue {
let error = js_sys::Error::new(RESET_REQUIRED_MESSAGE);
js_sys::Reflect::set(
error.as_ref(),
&JsValue::from_str(RESET_REQUIRED_MARKER),
&JsValue::TRUE,
)
.expect("new JavaScript Error accepts the reset marker");
error.into()
}
/// Converts an OPFS adapter error, marking a path another context kept open
/// for the whole busy wait with a `cacheStorageBusy` property of `true`.
fn storage_err_js(error: &OpfsError) -> JsValue {
let value = err_js(error);
if error.kind() == OpfsErrorKind::Busy {
js_sys::Reflect::set(
&value,
&JsValue::from_str(STORAGE_BUSY_MARKER),
&JsValue::TRUE,
)
.expect("new JavaScript Error accepts the busy marker");
}
value
}
fn owner_lock_unavailable_js_error() -> JsValue {
let error = js_sys::Error::new(OWNER_LOCK_UNAVAILABLE_MESSAGE);
js_sys::Reflect::set(
error.as_ref(),
&JsValue::from_str(OWNER_LOCK_UNAVAILABLE_MARKER),
&JsValue::TRUE,
)
.expect("new JavaScript Error accepts the unavailable marker");
error.into()
}
fn engine_error_requires_reset(error: &EngineError<TursoStorageError>) -> bool {
matches!(
error,
EngineError::Storage(storage_error) if storage_error.requires_physical_reset()
)
}
fn parse_variables(
variables: JsValue,
) -> Result<serde_json::Map<String, serde_json::Value>, JsValue> {
if variables.is_undefined() || variables.is_null() {
return Ok(serde_json::Map::new());
}
serde_wasm_bindgen::from_value(variables).map_err(err_js)
}
fn parse_vec<T: serde::de::DeserializeOwned>(value: JsValue) -> Result<Vec<T>, JsValue> {
if value.is_undefined() || value.is_null() {
return Ok(Vec::new());
}
serde_wasm_bindgen::from_value(value).map_err(err_js)
}
fn parse_query_inspection(
query: String,
operation_name: Option<String>,
path: JsValue,
variable_filters: Vec<serde_json::Map<String, serde_json::Value>>,
) -> Result<QueryInspection, JsValue> {
let path: Vec<JsInspectionPathSegment> =
serde_wasm_bindgen::from_value(path).map_err(err_js)?;
Ok(QueryInspection {
query,
operation_name,
path: path.into_iter().map(|segment| segment.field).collect(),
variable_filters,
})
}
async fn close_storage(storage: BrowserStorage, force_reset: bool) -> Result<OpfsOwner, JsValue> {
match unwrap_storage(storage).try_close().map_err(err_js)? {
TursoStorageCloseOutcome::Healthy(closed) if force_reset => {
closed.reset().await.map_err(err_js)
}
TursoStorageCloseOutcome::Healthy(closed) => closed.preserve().map_err(err_js),
TursoStorageCloseOutcome::ResetRequired(closed) => closed.reset().await.map_err(err_js),
}
}
#[wasm_bindgen]
impl CacheEngine {
/// Returns payload-free durable mutation queue diagnostics.
#[wasm_bindgen(js_name = queueDiagnostics)]
pub fn queue_diagnostics(&self) -> js_sys::Promise {
let state = self.state.clone();
future_to_promise(async move {
let mut state = state.lock().await;
// Observation failures bypass `engine_result`: diagnostics never
// latch reset-required state or alter the engine lifecycle.
let diagnostics = state
.engine_mut()?
.queue_diagnostics()
.await
.map_err(err_js)?;
let value = js_sys::Object::new();
let available = diagnostics.availability == QueueDiagnosticsAvailability::Available;
js_sys::Reflect::set(
&value,
&JsValue::from_str("availability"),
&JsValue::from_str(if available {
"available"
} else {
"unavailable"
}),
)?;
js_sys::Reflect::set(
&value,
&JsValue::from_str("depth"),
&if available {
JsValue::from_str(&diagnostics.depth.to_string())
} else {
JsValue::NULL
},
)?;
js_sys::Reflect::set(
&value,
&JsValue::from_str("oldestCreatedAtMs"),
&if available {
diagnostics
.oldest_created_at_ms
.map_or(JsValue::NULL, |timestamp| {
JsValue::from_str(×tamp.to_string())
})
} else {
JsValue::NULL
},
)?;
Ok(value.into())
})
}
/// Returns the current in-memory cache revision as an unsigned decimal string.
#[wasm_bindgen(js_name = currentRevision)]
pub fn current_revision(&self) -> js_sys::Promise {
let state = self.state.clone();
future_to_promise(async move {
let mut state = state.lock().await;
let revision = state.engine_mut()?.current_revision();
Ok(JsValue::from_str(&revision.to_string()))
})
}
/// Returns the durable cache generation, initializing it when absent.
#[wasm_bindgen(js_name = currentStorageGeneration)]
pub fn current_storage_generation(&self) -> js_sys::Promise {
let state = self.state.clone();
future_to_promise(async move {
let mut state = state.lock().await;
let result = state.engine_mut()?.current_storage_generation().await;
let generation = state.engine_result(result)?;
Ok(JsValue::from_str(&generation.to_string()))
})
}
/// Returns the opaque identity bound to this cache, or `null` when no
/// identity-bearing response has been stored yet.
#[wasm_bindgen(js_name = boundIdentity)]
pub fn bound_identity(&self) -> js_sys::Promise {
let state = self.state.clone();
future_to_promise(async move {
let mut state = state.lock().await;
let result = state.engine_mut()?.current_identity().await;
let identity = state.engine_result(result)?;
to_js(&identity)
})
}
/// Attempts a cache read. Resolves to `{kind:"hit",data}` or
/// `{kind:"miss"}`. When `opId` is given, the operation is registered
/// as active for dependency-driven re-execution.
#[wasm_bindgen(js_name = readQuery)]
pub fn read_query(
&self,
op_id: Option<String>,
query: String,
operation_name: Option<String>,
variables: JsValue,
entity_resolvers: JsValue,
) -> js_sys::Promise {
let state = self.state.clone();
let ops = self.ops.clone();
future_to_promise(async move {
let mut state = state.lock().await;
state.ensure_callable()?;
let vars = parse_variables(variables)?;
let entity_resolvers: Vec<EntityResolver> = parse_vec(entity_resolvers)?;
let op = op_id.map(|name| ops.borrow_mut().intern(&name));
let result = state
.engine_mut()?
.read_query_with_entity_resolvers(
op,
&query,
operation_name.as_deref(),
&vars,
&entity_resolvers,
)
.await;
let result = state.engine_result(result)?;
let response = match result {
ReadResult::Hit { data } => JsReadResult::Hit { data },
ReadResult::Miss => JsReadResult::Miss,
};
let data = match &response {
JsReadResult::Hit { data } => Some(data),
JsReadResult::Miss => None,
};
read_response_to_js(&response, data)
})
}
/// Incrementally projects an ordinary query at one engine revision.
#[wasm_bindgen(js_name = watchQuery)]
pub fn watch_query(
&self,
op_id: String,
query: String,
operation_name: Option<String>,
variables: JsValue,
entity_resolvers: JsValue,
since: Option<String>,
) -> js_sys::Promise {
let state = self.state.clone();
let ops = self.ops.clone();
future_to_promise(async move {
let mut state = state.lock().await;
state.ensure_callable()?;
let variables = parse_variables(variables)?;
let entity_resolvers: Vec<EntityResolver> = parse_vec(entity_resolvers)?;
let since = since
.map(|value| value.parse())
.transpose()
.map_err(err_js)?;
let op = ops.borrow_mut().intern(&op_id);
let result = state
.engine_mut()?
.watch_query(
op,
&query,
operation_name.as_deref(),
&variables,
&entity_resolvers,
since,
)
.await;
let result = state.engine_result(result)?;
read_response_to_js(&result, query_update_values(&result))
})
}
/// Projects explicit normalized entity keys through a named GraphQL
/// fragment without scanning storage.
#[wasm_bindgen(js_name = readRecordsByKeys)]
pub fn read_records_by_keys(
&self,
document: String,
fragment_name: String,
keys: JsValue,
) -> js_sys::Promise {
let state = self.state.clone();
future_to_promise(async move {
let mut state = state.lock().await;
state.ensure_callable()?;
let schema = state.engine_mut()?.schema_snapshot();
let selection = state
.selections
.get(&schema, document, fragment_name)
.map_err(err_js)?;
let keys: Vec<String> = parse_vec(keys)?;
let keys: Vec<_> = keys.into_iter().map(|key| EntityKey(key.into())).collect();
let result = state
.engine_mut()?
.read_records_by_keys(&selection, &keys)
.await;
let records = state.engine_result(result)?;
let response = JsRecordSelectionResult {
revision: records.revision.to_string(),
records: records.value,
};
read_response_to_js(
&response,
response.records.iter().map(|record| &record.record),
)
})
}
/// Searches the compact materialized projection. Empty queries use the
/// indexed recent path; text queries rank the compact catalog without
/// scanning normalized record blobs.
pub fn search(&self, request: JsValue) -> js_sys::Promise {
let state = self.state.clone();
future_to_promise(async move {
let mut state = state.lock().await;
state.ensure_callable()?;
let request: SearchRequest = serde_wasm_bindgen::from_value(request).map_err(err_js)?;
let result = state.engine_mut()?.search(&request).await;
let page = state.engine_result(result)?;
to_js(&page)
})
}
/// Evaluates one exact current-profile GraphQL Soup filter request.
#[wasm_bindgen(js_name = entityFilter)]
pub fn entity_filter(&self, request: JsValue) -> js_sys::Promise {
let state = self.state.clone();
future_to_promise(async move {
let mut state = state.lock().await;
state.ensure_callable()?;
let request: JsEntityFilterRequest =
serde_wasm_bindgen::from_value(request).map_err(err_js)?;
if let Some(live) = &request.live_query {
if live.release {
state.engine_mut()?.release_live_query(&live.id);
return to_js(&JsEntityFilterResult::Unsupported);
}
if request.mail.is_some() || request.baseline.is_none() {
return Err(err_js(
"live queries require a reconciled baseline and do not accept mail cursors",
));
}
}
if let Some(mail) = request.mail {
let baseline = request
.baseline
.unwrap_or_default()
.into_iter()
.map(|entry| {
soup_filter_cache_adapter::reconciliation_baseline_entry(
entry.key,
&entry.sort_timestamp,
)
})
.collect::<Result<Vec<_>, _>>()
.map_err(err_js)?;
let generation = state.mail_generation.clone();
let result = soup_filter_cache_adapter::mail::page_current(
state.engine_mut()?,
&generation,
request.filters,
&request.sort_method,
&request.sort_direction,
request.limit,
mail,
&baseline,
)
.await
.map_err(|error| match error {
soup_filter_cache_adapter::mail::PageError::Engine(error) => {
state.engine_error(error)
}
soup_filter_cache_adapter::mail::PageError::Adapter(error) => err_js(error),
})?;
return to_js(&result);
}
let outcome = compile_filter_request(
request.filters,
&request.sort_method,
&request.sort_direction,
request.limit,
)
.map_err(err_js)?;
let result = match outcome {
SoupFilterCompileOutcome::Unsupported => JsEntityFilterResult::Unsupported,
SoupFilterCompileOutcome::Supported(query) if request.baseline.is_some() => {
let baseline = request.baseline.unwrap();
if baseline.len()
> cache_core::predicate::reconciliation::MAX_RECONCILIATION_BASELINE
{
return Err(err_js("reconciliation baseline is too large"));
}
let baseline = baseline
.into_iter()
.map(|entry| {
soup_filter_cache_adapter::reconciliation_baseline_entry(
entry.key,
&entry.sort_timestamp,
)
})
.collect::<Result<Vec<_>, _>>()
.map_err(err_js)?;
if let Some(live) = request.live_query {
let schema = state.engine_mut()?.schema_snapshot();
let selection = state
.selections
.get(&schema, live.document, live.fragment_name)
.map_err(err_js)?;
let since = live
.since
.map(|revision| revision.parse::<cache_core::revision::CacheRevision>())
.transpose()
.map_err(err_js)?;
let result = state
.engine_mut()?
.read_live_query(
&live.id,
cache_core::engine::live_query::LiveQuerySpec {
query,
baseline,
selection,
},
since,
)
.await;
let update = state.engine_result(result)?;
return to_js(&JsEntityFilterResult::LiveQuery { update });
}
let result = state
.engine_mut()?
.reconcile_predicate_index(&query, &baseline)
.await;
let result = state.engine_result(result)?;
JsEntityFilterResult::Reconciled {
revision: result.revision.to_string(),
keys: result
.value
.keys
.into_iter()
.map(|key| key.as_str().to_owned())
.collect(),
retained_keys: result
.value
.retained_keys
.into_iter()
.map(|key| key.as_str().to_owned())
.collect(),
optimistic: result.value.optimistic,
}
}
SoupFilterCompileOutcome::Supported(query) => {
let result = state.engine_mut()?.query_predicate_index(&query).await;
let result = state.engine_result(result)?;
let revision = result.revision.to_string();
match result.value {
PredicateQueryResult::Complete(keys) => JsEntityFilterResult::Complete {
revision,
keys: keys
.into_iter()
.map(|key| key.as_str().to_owned())
.collect(),
optimistic: false,
},
PredicateQueryResult::Optimistic(keys) => JsEntityFilterResult::Complete {
revision,
keys: keys
.into_iter()
.map(|key| key.as_str().to_owned())
.collect(),
optimistic: true,
},
PredicateQueryResult::Incomplete => {
JsEntityFilterResult::Incomplete { revision }
}
}
}
};
to_js(&result)
})
}
/// Normalizes and stores a network response. Resolves to
/// `{changed: string[], affectedOps: string[], reset: boolean}` —
/// `affectedOps` are the registered operation ids (excluding
/// `originOpId`) whose data changed. `identity` is an opaque session tag
/// (extracted by the exchange from the response); a tag mismatching the
/// cache's bound identity wipes and rebinds atomically with this write.
#[wasm_bindgen(js_name = writeQuery)]
pub fn write_query(
&self,
context: JsValue,
query: String,
operation_name: Option<String>,
variables: JsValue,
data: JsValue,
identity: Option<String>,
) -> js_sys::Promise {
let state = self.state.clone();
let ops = self.ops.clone();
future_to_promise(async move {
let mut state = state.lock().await;
state.ensure_callable()?;
let context: JsWriteContext =
serde_wasm_bindgen::from_value(context).map_err(err_js)?;
let vars = parse_variables(variables)?;
let data: serde_json::Value = serde_wasm_bindgen::from_value(data).map_err(err_js)?;
let origin = context
.origin_op_id
.map(|name| ops.borrow_mut().intern(&name));
let registration = context.registration.map(|registration| {
let op_id = ops.borrow_mut().intern(®istration.op_id);
(op_id, registration.entity_resolvers)
});
let mut projections = authoritative_projection_mutations(
&state.engine_mut()?.schema_snapshot(),
&query,
operation_name.as_deref(),
&data,
)
.map_err(err_js)?;
let reuse_stored_identity =
state.can_reuse_stored_identity(identity.as_deref()).await?;
if reuse_stored_identity {
projections.extend(
notification_projection_updates(
&state.engine_mut()?.schema_snapshot(),
state.engine_mut()?.storage(),
&query,
operation_name.as_deref(),
&vars,
&data,
)
.await
.map_err(err_js)?,
);
}
projections.extend(
soup_filter_cache_adapter::mail::projection_updates_for_write(
&state.engine_mut()?.schema_snapshot(),
state.engine_mut()?.storage(),
&query,
operation_name.as_deref(),
&vars,
&data,
reuse_stored_identity,
)
.await
.map_err(|error| state.mail_projection_error(error))?,
);
let projections = soup_filter_cache_adapter::properties::augment_authoritative(
&state.engine_mut()?.schema_snapshot(),
state.engine_mut()?.storage(),
&query,
operation_name.as_deref(),
&vars,
&data,
reuse_stored_identity,
projections,
)
.await
.map_err(|error| state.mail_projection_error(error))?;
let result = state
.engine_mut()?
.write_query_with_registration_and_projections(
origin,
registration
.as_ref()
.map(|(op_id, entity_resolvers)| QueryRegistration {
op_id: *op_id,
entity_resolvers,
}),
NetworkWrite {
query: &query,
operation_name: operation_name.as_deref(),
variables: &vars,
data: &data,
identity: identity.as_deref(),
},
projections,
)
.await;
let result = state.engine_result(result)?;
to_js(&js_write_result(result, &ops.borrow()))
})
}
/// Normalizes and stores a query response while returning only fields not
/// marked `@cacheOnly` in the GraphQL document.
#[wasm_bindgen(js_name = hydrateQuery)]
pub fn hydrate_query(
&self,
query: String,
operation_name: Option<String>,
variables: JsValue,
data: JsValue,
identity: Option<String>,
) -> js_sys::Promise {
let state = self.state.clone();
let ops = self.ops.clone();
future_to_promise(async move {
let mut state = state.lock().await;
state.ensure_callable()?;
let variables = parse_variables(variables)?;
let data: serde_json::Value = serde_wasm_bindgen::from_value(data).map_err(err_js)?;
let mut projections = authoritative_projection_mutations(
&state.engine_mut()?.schema_snapshot(),
&query,
operation_name.as_deref(),
&data,
)
.map_err(err_js)?;
let reuse_stored_identity =
state.can_reuse_stored_identity(identity.as_deref()).await?;
if reuse_stored_identity {
projections.extend(
notification_projection_updates(
&state.engine_mut()?.schema_snapshot(),
state.engine_mut()?.storage(),
&query,
operation_name.as_deref(),
&variables,
&data,
)
.await
.map_err(err_js)?,
);
}
projections.extend(
soup_filter_cache_adapter::mail::projection_updates_for_write(
&state.engine_mut()?.schema_snapshot(),
state.engine_mut()?.storage(),
&query,
operation_name.as_deref(),
&variables,
&data,
reuse_stored_identity,
)
.await
.map_err(|error| state.mail_projection_error(error))?,
);
let projections = soup_filter_cache_adapter::properties::augment_authoritative(
&state.engine_mut()?.schema_snapshot(),
state.engine_mut()?.storage(),
&query,
operation_name.as_deref(),
&variables,
&data,
reuse_stored_identity,
projections,
)
.await
.map_err(|error| state.mail_projection_error(error))?;
let result = state
.engine_mut()?
.hydrate_query_with_projections(
&query,
operation_name.as_deref(),
&variables,
&data,
identity.as_deref(),
projections,
)
.await;
let result = state.engine_result(result)?;
// A failed optional proof must still deliver the committed write and broad invalidation.
let unchanged_views = state
.engine_mut()?
.unchanged_observed_windows()
.await
.unwrap_or_default();
to_js(&JsHydrationWriteResult {
unchanged_views,
search_changed_buckets: result.search_changed_buckets,
revision: result.write_result.revision.to_string(),
revision_advanced: result.write_result.revision_advanced,
changed: result
.write_result
.changed
.into_iter()
.map(|key| key.0.into_owned())
.collect(),
affected_ops: ops.borrow().names(result.write_result.affected_ops),
reset: result.write_result.reset,
revalidations: result.write_result.revalidations,
mutation_uuid: result.write_result.mutation_uuid,
data: result.data,
})
})
}
/// Durably queues a mutation and its optimistic response, then attempts
/// to claim the strict queue head before resolving. Claim failures are
/// returned as a nested diagnostic outcome because enqueue succeeded.
#[wasm_bindgen(js_name = enqueueOptimisticMutation)]
#[allow(clippy::too_many_arguments)]
pub fn enqueue_optimistic_mutation(
&self,
origin_op_id: Option<String>,
uuid: String,
query: String,
operation_name: Option<String>,
variables: JsValue,
data: JsValue,
link_patches: JsValue,
revalidations: JsValue,
identity_bindings: JsValue,
created_at_ms: f64,
lease_owner: String,
now_ms: f64,
lease_expires_at_ms: f64,
client_metadata: JsValue,
uncertain_calendar_event_keys: JsValue,
) -> js_sys::Promise {
let state = self.state.clone();
let ops = self.ops.clone();
future_to_promise(async move {
let mut state = state.lock().await;
state.ensure_callable()?;
let vars = parse_variables(variables)?;
let client_metadata: Option<serde_json::Value> =
serde_wasm_bindgen::from_value(client_metadata).map_err(err_js)?;
let data: serde_json::Value = serde_wasm_bindgen::from_value(data).map_err(err_js)?;
let link_patches: Vec<OptimisticLinkPatch> = parse_vec(link_patches)?;
let revalidations: Vec<QueryRevalidation> = parse_vec(revalidations)?;
let identity_bindings: Vec<cache_core::identity::IdentityBinding> =
parse_vec(identity_bindings)?;
let uncertain_calendar_event_keys: Vec<EntityKey<'static>> =
parse_vec(uncertain_calendar_event_keys)?;
let created_at_ms = parse_timestamp(created_at_ms, "enqueue timestamp")?;
let mut projection_mutations = optimistic_projection_mutations(&data, created_at_ms);
projection_mutations.extend(
optimistic_notification_updates(
notification_projection_updates(
&state.engine_mut()?.schema_snapshot(),
state.engine_mut()?.storage(),
&query,
operation_name.as_deref(),
&vars,
&data,
)
.await
.map_err(err_js)?,
)
.map_err(err_js)?,
);
projection_mutations.extend(soup_filter_cache_adapter::mail::optimistic_updates(
soup_filter_cache_adapter::mail::projection_updates(
&state.engine_mut()?.schema_snapshot(),
state.engine_mut()?.storage(),
&query,
operation_name.as_deref(),
&vars,
&data,
)
.await
.map_err(|error| state.mail_projection_error(error))?,
));
projection_mutations.extend(
soup_filter_cache_adapter::mail::draft_optimistic_updates(
&state.engine_mut()?.schema_snapshot(),
state.engine_mut()?.storage(),
&query,
operation_name.as_deref(),
&vars,
&data,
)
.await
.map_err(|error| state.mail_projection_error(error))?,
);
let projection_mutations = soup_filter_cache_adapter::properties::augment_optimistic(
&state.engine_mut()?.schema_snapshot(),
state.engine_mut()?.storage(),
&query,
operation_name.as_deref(),
&vars,
&data,
projection_mutations,
)
.await
.map_err(|error| state.mail_projection_error(error))?;
let claim = MutationClaimRequest {
owner: lease_owner,
now_ms: parse_timestamp(now_ms, "claim timestamp")?,
lease_expires_at_ms: parse_timestamp(
lease_expires_at_ms,
"lease expiration timestamp",
)?,
};
let origin = origin_op_id.map(|name| ops.borrow_mut().intern(&name));
let result = state
.engine_mut()?
.enqueue_optimistic_mutation_with_calendar(
origin,
BeginOptimisticWrite {
client_metadata: client_metadata.as_ref(),
uuid: &uuid,
query: &query,
operation_name: operation_name.as_deref(),
variables: &vars,
data: &data,
link_patches: &link_patches,
revalidations: &revalidations,
created_at_ms,
identity_bindings: &identity_bindings,
},
claim,
projection_mutations,
uncertain_calendar_event_keys,
)
.await;
let result = state.engine_result(result)?;
let initial_claim = match result.initial_claim {
InitialClaimOutcome::Claimed(claimed) => JsInitialMutationClaim::Claimed {
mutation: JsClaimedMutation::try_from(*claimed)?,
},
InitialClaimOutcome::NotRunnable => JsInitialMutationClaim::NotRunnable,
InitialClaimOutcome::Failed(error) if engine_error_requires_reset(&error) => {
return Err(state.engine_error(error));
}
InitialClaimOutcome::Failed(error) => JsInitialMutationClaim::Failed {
error: error.to_string(),
},
};
to_js(&JsEnqueueOptimisticMutationResult {
field_changes: result.write_result.field_changes,
transaction_id: result.transaction_id.to_string(),
upsert_kind: result.upsert_kind.into(),
revision: result.write_result.revision.to_string(),
revision_advanced: result.write_result.revision_advanced,
changed: result
.write_result
.changed
.into_iter()
.map(|key| key.0.into_owned())
.collect(),
affected_ops: ops.borrow().names(result.write_result.affected_ops),
reset: result.write_result.reset,
revalidations: result.write_result.revalidations,
mutation_uuid: result.write_result.mutation_uuid,
initial_claim,
})
})
}
/// Recovers cached query variables without materializing each variant.
#[wasm_bindgen(js_name = inspectQueryVariants)]
pub fn inspect_query_variants(
&self,
query: String,
operation_name: Option<String>,
path: JsValue,
) -> js_sys::Promise {
let state = self.state.clone();
future_to_promise(async move {
let mut state = state.lock().await;
state.ensure_callable()?;
let inspection = parse_query_inspection(query, operation_name, path, Vec::new())?;
let result = state
.engine_mut()?
.inspect_query_variants(&inspection)
.await;
let variants = state.engine_result(result)?;
to_js(&variants)
})
}
/// Enumerates and materializes cached variants of one generated query field.
#[wasm_bindgen(js_name = inspectQuery)]
pub fn inspect_query(
&self,
query: String,
operation_name: Option<String>,
path: JsValue,
variable_filters: JsValue,
) -> js_sys::Promise {
let state = self.state.clone();
future_to_promise(async move {
let mut state = state.lock().await;
state.ensure_callable()?;
let variable_filters = parse_vec(variable_filters)?;
let inspection = parse_query_inspection(query, operation_name, path, variable_filters)?;
let result = state.engine_mut()?.inspect_query(&inspection).await;
let instances = state.engine_result(result)?;
to_js(&instances)
})
}
/// Inspects durable mutations without claiming them.
#[wasm_bindgen(js_name = inspectMutations)]
pub fn inspect_mutations(&self) -> js_sys::Promise {
let state = self.state.clone();
future_to_promise(async move {
let mut state = state.lock().await;
state.ensure_callable()?;
let result = state.engine_mut()?.inspect_mutations().await;
to_js(&state.engine_result(result)?)
})
}
/// Claims the oldest runnable queued mutation.
#[wasm_bindgen(js_name = claimNextMutation)]
pub fn claim_next_mutation(
&self,
owner: String,
now_ms: f64,
lease_expires_at_ms: f64,
) -> js_sys::Promise {
let state = self.state.clone();
future_to_promise(async move {
let mut state = state.lock().await;
state.ensure_callable()?;
let request = MutationClaimRequest {
owner,
now_ms: parse_timestamp(now_ms, "claim timestamp")?,
lease_expires_at_ms: parse_timestamp(
lease_expires_at_ms,
"lease expiration timestamp",
)?,
};
let result = state.engine_mut()?.claim_next_mutation(request).await;
let claimed = state.engine_result(result)?;
to_js(&claimed.map(JsClaimedMutation::try_from).transpose()?)
})
}
/// Retains a retryable mutation and releases its queue lease.
#[wasm_bindgen(js_name = deferOptimisticWrite)]
pub fn defer_optimistic_write(
&self,
transaction_id: String,
lease_owner: String,
lease_generation: String,
next_attempt_at_ms: f64,
error: String,
server_failure: bool,
) -> js_sys::Promise {
let state = self.state.clone();
let ops = self.ops.clone();
future_to_promise(async move {
let mut state = state.lock().await;
state.ensure_callable()?;
let transaction = parse_transaction_id(&transaction_id)?;
let claim = MutationClaimToken {
owner: lease_owner,
generation: parse_u64(&lease_generation, "lease generation")?,
};
let next_attempt_at_ms = parse_timestamp(next_attempt_at_ms, "next attempt timestamp")?;
let result = state
.engine_mut()?
.defer_optimistic_write(
transaction,
claim,
next_attempt_at_ms,
error,
server_failure,
)
.await;
let result = state.engine_result(result)?;
let result = match result {
DeferOptimisticWriteResult::Deferred => JsDeferOptimisticWriteResult::Deferred,
DeferOptimisticWriteResult::DiscardedSuperseded(result) => {
JsDeferOptimisticWriteResult::DiscardedSuperseded {
replacement_transaction_id: result.replacement_transaction_id.to_string(),
result: js_write_result(result.write_result, &ops.borrow()),
}
}
};
to_js(&result)
})
}
/// Atomically replaces a claimed optimistic layer with the real network
/// response and removes it from the durable queue.
#[wasm_bindgen(js_name = commitOptimisticWrite)]
#[allow(clippy::too_many_arguments)]
pub fn commit_optimistic_write(
&self,
transaction_id: String,
lease_owner: String,
lease_generation: String,
query: String,
operation_name: Option<String>,
variables: JsValue,
data: JsValue,
) -> js_sys::Promise {
let state = self.state.clone();
let ops = self.ops.clone();
future_to_promise(async move {
let mut state = state.lock().await;
state.ensure_callable()?;
let transaction = parse_transaction_id(&transaction_id)?;
let claim = MutationClaimToken {
owner: lease_owner,
generation: parse_u64(&lease_generation, "lease generation")?,
};
let vars = parse_variables(variables)?;
let data: serde_json::Value = serde_wasm_bindgen::from_value(data).map_err(err_js)?;
let mut projections = authoritative_projection_mutations(
&state.engine_mut()?.schema_snapshot(),
&query,
operation_name.as_deref(),
&data,
)
.map_err(err_js)?;
projections.extend(
notification_projection_updates(
&state.engine_mut()?.schema_snapshot(),
state.engine_mut()?.storage(),
&query,
operation_name.as_deref(),
&vars,
&data,
)
.await
.map_err(err_js)?,
);
projections.extend(
soup_filter_cache_adapter::mail::projection_updates(
&state.engine_mut()?.schema_snapshot(),
state.engine_mut()?.storage(),
&query,
operation_name.as_deref(),
&vars,
&data,
)
.await
.map_err(|error| state.mail_projection_error(error))?,
);
let projections = soup_filter_cache_adapter::properties::augment_authoritative(
&state.engine_mut()?.schema_snapshot(),
state.engine_mut()?.storage(),
&query,
operation_name.as_deref(),
&vars,
&data,
true,
projections,
)
.await
.map_err(|error| state.mail_projection_error(error))?;
let result = state
.engine_mut()?
.commit_optimistic_write_with_projections_outcome(
transaction,
claim,
&query,
operation_name.as_deref(),
&vars,
&data,
projections,
)
.await;
let result = match state.engine_result(result)? {
CommitOptimisticWriteResult::Failed(result) => {
JsCommitOptimisticWriteResult::Failed {
error: result.error,
replacement_transaction_id: result
.replacement_transaction_id
.map(|id| id.to_string()),
result: js_write_result(result.write_result, &ops.borrow()),
}
}
CommitOptimisticWriteResult::Committed(result) => {
JsCommitOptimisticWriteResult::Committed {
result: js_write_result(result, &ops.borrow()),
}
}
CommitOptimisticWriteResult::CommittedSuperseded(result) => {
JsCommitOptimisticWriteResult::CommittedSuperseded {
replacement_transaction_id: result.replacement_transaction_id.to_string(),
result: js_write_result(result.write_result, &ops.borrow()),
}
}
};
to_js(&result)
})
}
/// Permanently fails a claimed mutation and removes its optimistic
/// contribution.
#[wasm_bindgen(js_name = rollbackOptimisticWrite)]
pub fn rollback_optimistic_write(
&self,
transaction_id: String,
lease_owner: String,
lease_generation: String,
) -> js_sys::Promise {
let state = self.state.clone();
let ops = self.ops.clone();
future_to_promise(async move {
let mut state = state.lock().await;
state.ensure_callable()?;
let transaction = parse_transaction_id(&transaction_id)?;
let claim = MutationClaimToken {
owner: lease_owner,
generation: parse_u64(&lease_generation, "lease generation")?,
};
let result = state
.engine_mut()?
.rollback_optimistic_write_with_outcome(transaction, claim)
.await;
let result = match state.engine_result(result)? {
RollbackOptimisticWriteResult::RolledBack(result) => {
JsRollbackOptimisticWriteResult::RolledBack {
result: js_write_result(result, &ops.borrow()),
}
}
RollbackOptimisticWriteResult::DiscardedSuperseded(result) => {
JsRollbackOptimisticWriteResult::DiscardedSuperseded {
replacement_transaction_id: result.replacement_transaction_id.to_string(),
result: js_write_result(result.write_result, &ops.borrow()),
}
}
};
to_js(&result)
})
}
/// Evicts externally-changed records from the hot tier (cross-tab
/// broadcasts, push invalidation). Resolves to the affected local
/// operation ids.
#[wasm_bindgen(js_name = invalidateKeys)]
pub fn invalidate_keys(&self, keys: Vec<String>) -> js_sys::Promise {
let state = self.state.clone();
let ops = self.ops.clone();
future_to_promise(async move {
let mut state = state.lock().await;
state.ensure_callable()?;
let mut projections = dirty_projection_mutations(&keys);
projections.extend(soup_filter_cache_adapter::mail::dirty_updates(&keys));
projections.extend(
notification_deletion_updates(state.engine_mut()?.storage(), &keys, true)
.await
.map_err(err_js)?,
);
let keys: Vec<EntityKey<'static>> =
keys.into_iter().map(|key| EntityKey(key.into())).collect();
projections.extend(
soup_filter_cache_adapter::properties::deletion_updates(
state.engine_mut()?.storage(),
&keys.iter().map(ToString::to_string).collect::<Vec<_>>(),
)
.await
.map_err(|error| state.mail_projection_error(error))?,
);
let projections = soup_filter_cache_adapter::properties::current_mutations(projections);
let result = state
.engine_mut()?
.invalidate_keys_with_projections(&keys, projections)
.await;
let affected = state.engine_result(result)?;
to_js(&JsAffectedOperationsResult {
revision: affected.revision.to_string(),
affected_ops: ops.borrow().names(affected.value),
})
})
}
/// Deletes stale records from memory and Turso after a server-side
/// mutation and resolves to affected local operation ids.
#[wasm_bindgen(js_name = deleteKeys)]
pub fn delete_keys(&self, keys: Vec<String>) -> js_sys::Promise {
let state = self.state.clone();
let ops = self.ops.clone();
future_to_promise(async move {
let mut state = state.lock().await;
state.ensure_callable()?;
let mut projections =
notification_deletion_updates(state.engine_mut()?.storage(), &keys, false)
.await
.map_err(err_js)?;
projections.extend(
keys.iter()
.filter_map(|key| RecordKey::new(key.clone()).ok())
.map(cache_core::predicate::ProjectionMutation::Delete),
);
let keys: Vec<EntityKey<'static>> =
keys.into_iter().map(|key| EntityKey(key.into())).collect();
projections.extend(
soup_filter_cache_adapter::properties::deletion_updates(
state.engine_mut()?.storage(),
&keys.iter().map(ToString::to_string).collect::<Vec<_>>(),
)
.await
.map_err(|error| state.mail_projection_error(error))?,
);
let projections = soup_filter_cache_adapter::properties::current_mutations(projections);
let result = state
.engine_mut()?
.delete_keys_with_projection_changes(&keys, projections)
.await;
let affected = state.engine_result(result)?;
to_js(&JsAffectedOperationsResult {
revision: affected.revision.to_string(),
affected_ops: ops.borrow().names(affected.value),
})
})
}
/// Reloads optimistic layers after another engine changes the durable
/// queue and returns locally affected operations.
#[wasm_bindgen(js_name = refreshOptimisticQueue)]
pub fn refresh_optimistic_queue(&self) -> js_sys::Promise {
let state = self.state.clone();
let ops = self.ops.clone();
future_to_promise(async move {
let mut state = state.lock().await;
let result = state.engine_mut()?.refresh_optimistic_queue().await;
let result = state.engine_result(result)?;
to_js(&js_write_result(result, &ops.borrow()))
})
}
/// Reacts to a cache reset performed by another engine instance sharing
/// the same storage (cross-tab broadcast). Drops local in-memory state
/// and resolves to every local operation id (all must re-execute).
#[wasm_bindgen(js_name = externalReset)]
pub fn external_reset(&self) -> js_sys::Promise {
let state = self.state.clone();
let ops = self.ops.clone();
future_to_promise(async move {
let mut state = state.lock().await;
let result = state.engine_mut()?.external_reset();
let affected = state.engine_result(result)?;
to_js(&JsAffectedOperationsResult {
revision: affected.revision.to_string(),
affected_ops: ops.borrow().names(affected.value),
})
})
}
/// Unregisters an operation (urql teardown).
#[wasm_bindgen(js_name = teardownOperation)]
pub fn teardown_operation(&self, op_id: String) -> js_sys::Promise {
let state = self.state.clone();
let ops = self.ops.clone();
future_to_promise(async move {
let mut state = state.lock().await;
let engine = state.engine_mut()?;
if let Some(id) = ops.borrow_mut().remove(&op_id) {
engine.teardown_operation(id);
}
Ok(JsValue::UNDEFINED)
})
}
/// Drops all cached state, including the durable mutation queue.
pub fn clear(&self) -> js_sys::Promise {
let state = self.state.clone();
future_to_promise(async move {
let mut state = state.lock().await;
let result = state.engine_mut()?.clear().await;
let revision = state.engine_result(result)?;
to_js(&JsRevisionResult {
revision: revision.to_string(),
})
})
}
/// Physically resets and recreates this instance's OPFS database while
/// retaining the exclusive owner lock. The instance remains usable after
/// the fresh engine has been installed.
#[wasm_bindgen(js_name = physicalReset)]
pub fn physical_reset(&self) -> js_sys::Promise {
let state = self.state.clone();
future_to_promise(async move {
let mut state = state.lock().await;
let engine = state.engine.take().ok_or_else(|| {
if state.reset_required {
err_js("cache engine requires worker replacement")
} else {
closed_js_error()
}
})?;
let scope = state.scope.clone();
let hot_capacity = state.hot_capacity;
let owner = match close_storage(engine.into_storage(), true).await {
Ok(owner) => owner,
Err(error) => {
state.reset_required = true;
return Err(error);
}
};
let storage = match open_storage(&scope, owner).await {
Ok(opened) => opened.storage,
Err(error) => {
state.reset_required = true;
return Err(error);
}
};
state.engine = Some(build_engine(storage, hot_capacity));
state.mail_generation = soup_filter_cache_adapter::mail::new_generation();
state.reset_required = false;
Ok(JsValue::UNDEFINED)
})
}
/// Consumes the engine, closes Turso and all OPFS handles, then preserves a
/// healthy database or resets a latched-unhealthy database before releasing
/// the exclusive owner lock. Every later instance method rejects.
pub fn close(&self) -> js_sys::Promise {
let state = self.state.clone();
future_to_promise(async move {
let mut state = state.lock().await;
let engine = state.engine.take().ok_or_else(|| {
if state.reset_required {
err_js("cache engine requires worker replacement")
} else {
closed_js_error()
}
})?;
let owner = match close_storage(engine.into_storage(), state.reset_required).await {
Ok(owner) => owner,
Err(error) => {
state.reset_required = true;
return Err(error);
}
};
if let Err(error) = owner.release().await {
state.reset_required = true;
return Err(err_js(error));
}
state.reset_required = false;
Ok(JsValue::UNDEFINED)
})
}
}
#[cfg(test)]
impl CacheEngine {
async fn arm_storage_fault(&self, fault: TestStorageFault) {
let state = self.state.lock().await;
state
.engine
.as_ref()
.expect("test cache contains an engine")
.storage()
.arm(fault);
}
}