@rbxts/dataforge 0.2.0 → 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PepeElToro41
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/index.d.ts

@@ -29,7 +29,7 @@ declare namespace dataforge {
 
 	/** How a store reaches storage. */
 	interface Hook {
-		/** Identifies this server. Session locks and transaction ids carry it. */
+		/** Identifies this server. Session lock and transaction ids are built from it. */
 		job_id: () => string;
 		/** Returns the handle for a named store. Called once per store name. */
 		get_datastore: (name: string) => DatastoreHandle;
@@ -115,16 +115,40 @@ declare namespace dataforge {
 		Configuration
 	*/
 
-	interface Migration {
+	/** A named migration whose output can be checked against a target schema. */
+	interface Migration<T = unknown> {
 		name: string;
-		apply: (data: unknown) => unknown;
+		/** Stored data may have an older shape; narrow it before reading fields. */
+		apply: (data: unknown) => T;
 	}
 
+	/** Earlier steps may return intermediate shapes; the last must return T. */
+	type Migrations<T = unknown> = [] | [...Migration[], Migration<T>];
+
+	/**
+	 * Decides whether this server may work with a key at all. `data` is the
+	 * raw stored data as it is in storage: `undefined` when the key does not
+	 * exist yet, and with the declared migrations *not* applied. Returning
+	 * `false` rejects the operation with a `predicate_failed` error: no lock
+	 * is taken and nothing is written.
+	 *
+	 * It runs inside the `update_async` transform, so it must be pure: no
+	 * yielding, no storage calls, and no mutation of `data`.
+	 */
+	type Predicate<T = unknown> = (data: T | undefined, key: string) => boolean;
+
 	interface Config<T = unknown> {
 		name: string;
 		template: T;
 
-		migrations?: Migration[];
+		/** The final output must match the template, rather than influence its inference. */
+		migrations?: Migrations<NoInfer<T>>;
+
+		/**
+		 * Gate on a key's stored data: every load, save, fetch and peek is
+		 * rejected with `predicate_failed` when it returns `false`.
+		 */
+		predicate?: Predicate<T>;
 
 		/** seconds, default 30 (locked profiles) */
 		autosave_interval?: number;
@@ -142,8 +166,13 @@ declare namespace dataforge {
 		retry_base?: number;
 	}
 
-	/** `Config<T>` with every optional field filled in. */
-	type ResolvedConfig<T = unknown> = Required<Config<T>>;
+	/**
+	 * `Config<T>` with every optional field filled in. `predicate` stays
+	 * optional: a store without one gates nothing.
+	 */
+	type ResolvedConfig<T = unknown> = Required<Omit<Config<T>, "predicate">> & {
+		predicate?: Predicate<T>;
+	};
 
 	interface TransactionConfig {
 		/**
@@ -167,6 +196,12 @@ declare namespace dataforge {
 	*/
 
 	interface Lock {
+		/**
+		 * Identifies the *acquisition* that holds the lock, not the server:
+		 * `{job_id}#{n}` for a profile's session lock, `{job_id}-{n}` for a
+		 * transaction's. Two sessions of one key on the same server hold
+		 * different ids, so they contend like sessions on different servers do.
+		 */
 		id: string;
 		expires: number;
 		/**
@@ -269,6 +304,21 @@ declare namespace dataforge {
 		readonly declared_migrations: string[];
 	}
 
+	/**
+	 * `config.predicate` returned `false` for a key's stored data: this server
+	 * must not work with that key. Nothing is written and no lock is taken.
+	 */
+	interface PredicateFailedError extends ErrorBase {
+		readonly type: "predicate_failed";
+		readonly key: string;
+		/** The operation the predicate rejected. */
+		readonly op: "load" | "save" | "fetch" | "peek";
+		/** The raw stored data the predicate rejected (`undefined` when the key is empty). */
+		readonly data: unknown;
+		/** The profile the call ran on; `undefined` for `store.load` and `store.peek`. */
+		readonly profile: AnyProfile<any> | undefined;
+	}
+
 	/** Lockless `get_data` before any fetch / flush. Thrown, never returned. */
 	interface NotFetchedError extends ErrorBase {
 		readonly type: "not_fetched";
@@ -335,6 +385,7 @@ declare namespace dataforge {
 		| LocklessLockedError
 		| TxLockLostError
 		| OutdatedError
+		| PredicateFailedError
 		| NotFetchedError
 		| ProfileClosedError
 		| MigrationMismatchError
@@ -387,7 +438,10 @@ declare namespace dataforge {
 		 * (`profile_closed`, or `not_fetched` for a lockless profile).
 		 */
 		get_data(): T;
-		/** Fails with `profile_closed`, `released`, `roblox`, `lock_lost` (locked) or `lockless_locked`, `outdated`, ... (lockless). */
+		/**
+		 * Fails with `profile_closed`, `released`, `roblox`, `predicate_failed`,
+		 * `lock_lost` (locked) or `lockless_locked`, `outdated`, ... (lockless).
+		 */
 		save(): Result<void>;
 		unload(): void;
 		/**
@@ -424,6 +478,11 @@ declare namespace dataforge {
 	interface Profile<T = unknown> extends ProfileBase<T> {
 		readonly kind: "locked";
 		readonly last_write: number;
+		/**
+		 * The id of this acquisition's lock; re-stamped unchanged on every
+		 * save, replaced by `readquire`. See `Lock.id`.
+		 */
+		readonly lock_id: string;
 		/**
 		 * Whether the profile currently holds its session lock. True after
 		 * `load`; `release` clears it, `readquire` takes it again. While
@@ -438,13 +497,14 @@ declare namespace dataforge {
 		/**
 		 * Writes the data and gives the session lock back, keeping the profile
 		 * open so another server may take the key. No-op when already released.
-		 * Fails with `profile_closed`, `roblox` or `lock_lost`.
+		 * Fails with `profile_closed`, `roblox`, `predicate_failed` or `lock_lost`.
 		 */
 		release(): Result<void>;
 		/**
 		 * Takes the session lock again (waits like `load` does) and adopts the
 		 * stored record as the current data. No-op when already locked. Fails
-		 * with `timeout`, `profile_closed`, `roblox`, `outdated`, `migration_mismatch`.
+		 * with `timeout`, `profile_closed`, `roblox`, `outdated`,
+		 * `predicate_failed`, `migration_mismatch`.
 		 */
 		readquire(): Result<void>;
 	}
@@ -461,7 +521,8 @@ declare namespace dataforge {
 		 * Reads the stored record into the local data: migrations are applied,
 		 * then the queued updates replayed on top. Marks the profile fetched.
 		 * Yields. Fails (keeping the queue) with `lockless_locked` if a session
-		 * lock is on the record, `outdated`, `roblox`, `migration_mismatch`, `profile_closed`.
+		 * lock is on the record, `outdated`, `predicate_failed`, `roblox`,
+		 * `migration_mismatch`, `profile_closed`.
 		 */
 		fetch(): Result<T>;
 	}
@@ -487,8 +548,8 @@ declare namespace dataforge {
 		get_data(): T;
 		/**
 		 * Calls `GetAsync` again and replaces `lock`, `pending`, `migrations`
-		 * and the data. Yields. Fails with `roblox`, `outdated` or `migration_mismatch`,
-		 * keeping the previous snapshot.
+		 * and the data. Yields. Fails with `roblox`, `predicate_failed`,
+		 * `outdated` or `migration_mismatch`, keeping the previous snapshot.
 		 */
 		refresh(): Result<T>;
 	}
@@ -514,9 +575,14 @@ declare namespace dataforge {
 		readonly lockless_profiles: ReadonlyMap<string, LocklessProfile<T>>;
 
 		/**
-		 * Takes the session lock for `key` and loads it. Yields. Fails with
-		 * `store_closed`, `already_loaded`, `timeout`, `roblox`,
-		 * `outdated`, `migration_mismatch` or `tx_marker_invalid`.
+		 * Takes the session lock for `key` and loads it. Yields. A profile that
+		 * is closing no longer counts as loaded: the load waits out its final
+		 * write through the record lock instead of failing `already_loaded`.
+		 *
+		 * Fails with `store_closed`, `already_loaded` (a profile for `key` is
+		 * still open on this store), `timeout`, `roblox`, `outdated`,
+		 * `predicate_failed` (`config.predicate` rejected the stored data; no
+		 * lock is taken), `migration_mismatch` or `tx_marker_invalid`.
 		 */
 		load(key: string, user_ids: number[]): Result<Profile<T>>;
 		/**
@@ -536,8 +602,8 @@ declare namespace dataforge {
 		/**
 		 * Read-only snapshot of `key` via `GetAsync`: the current data and lock.
 		 * Yields. The result is not tracked by the store, takes no lock and
-		 * cannot join a transaction. Fails with `store_closed`, `roblox`, `outdated`
-		 * or `migration_mismatch`.
+		 * cannot join a transaction. Fails with `store_closed`, `roblox`,
+		 * `outdated`, `predicate_failed` or `migration_mismatch`.
 		 */
 		peek(key: string): Result<PeekProfile<T>>;
 
@@ -554,6 +620,11 @@ declare namespace dataforge {
 			config?: TransactionConfig,
 		): Result<boolean>;
 
+		/**
+		 * Fires for every data change of every profile of this store, including
+		 * the data a key loads with (`oldData === undefined` marks that initial
+		 * value).
+		 */
 		on_change(callback: (profile: AnyProfile<T>, newData: T, oldData: T | undefined) => void): void;
 		on_save(callback: (profile: AnyProfile<T>) => void): void;
 		on_closing(callback: (profile: AnyProfile<T>) => void): void;
@@ -591,6 +662,29 @@ declare namespace dataforge {
 		config?: TransactionConfig,
 	): Result<boolean>;
 
+	/**
+	 * Whether `value` is a dataforge error (what a failed `Result` carries and
+	 * what the library throws internally). Lets a wrapper around library calls
+	 * tell a library error from any other thrown value.
+	 */
+	function is_error(value: unknown): boolean;
+
+	/**
+	 * The `Result` helpers, so you can build library-shaped results in your own
+	 * wrappers. `err` only accepts a dataforge error, so a malformed result
+	 * cannot be built with it.
+	 */
+	namespace result {
+		function ok<T>(value: T): Ok<T>;
+		function err(error: DataforgeError): Err;
+		/** Whether `value` is a `Result`. */
+		function is(value: unknown): boolean;
+		/** `Ok(value)` when `ok`, `Err` when `value` is a dataforge error, rethrown otherwise. */
+		function of<T>(ok: boolean, value: unknown): Result<T>;
+		/** `pcall(fn)` folded through `of`. */
+		function capture<T>(fn: () => T): Result<T>;
+	}
+
 	namespace hooks {
 		namespace memory {
 			function create(scheduler: Scheduler): MemoryHook;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rbxts/dataforge",
-  "version": "0.2.0",
+  "version": "0.4.1",
   "description": "Roblox DataStore library with cross-key transactions, session-locked and lockless profiles, migrations and an immutable data model.",
   "license": "MIT",
   "author": "PepeElToro41",
@@ -17,6 +17,9 @@
   ],
   "main": "src/init.luau",
   "types": "index.d.ts",
+  "scripts": {
+    "test:types": "tsc --project tests/types/tsconfig.json"
+  },
   "files": [
     "src",
     "index.d.ts",
@@ -27,6 +30,8 @@
     "access": "public"
   },
   "devDependencies": {
-    "@rbxts/types": "^1.0.947"
+    "@rbxts/compiler-types": "3.0.0-types.0",
+    "@rbxts/types": "^1.0.947",
+    "typescript": "5.5.3"
   }
 }

package/src/errors.luau

@@ -102,6 +102,22 @@ function errors.outdated(
 	}
 end
 
+function errors.predicate_failed(
+	key: string,
+	op: "load" | "save" | "fetch" | "peek",
+	data: any,
+	profile: any?
+): types.PredicateFailedError
+	return make {
+		type = "predicate_failed" :: "predicate_failed",
+		message = `datastore: the store predicate rejected the stored data of "{key}" (on {op})`,
+		key = key,
+		op = op,
+		data = data,
+		profile = profile,
+	}
+end
+
 function errors.not_fetched(profile: any): types.NotFetchedError
 	return make {
 		type = "not_fetched" :: "not_fetched",

package/src/init.luau

@@ -1,3 +1,5 @@
+local errors = require "@self/errors"
+local result = require "@self/result"
 local store = require "@self/store"
 local tx = require "@self/tx/handle"
 local types = require "@self/types"
@@ -20,6 +22,8 @@ export type ProfileBase<T = any> = types.ProfileBase<T>
 export type PeekProfile<T = any> = types.PeekProfile<T>
 export type Result<T> = types.Result<T>
 export type Error = types.Error
+export type Migration = types.Migration
+export type DataDispatcher<T = any> = types.DataDispatcher<T>
 
 local dataforge = {}
 
@@ -49,6 +53,16 @@ function dataforge.transaction(
 	return tx.run(tx.resolve_config(config, defaults), profiles, process)
 end
 
+--- Whether `value` is a dataforge `Error` table (what a failed Result carries
+--- and what the library throws internally). Lets a wrapper around library calls
+--- tell a library error from any other thrown value.
+dataforge.is_error = errors.is
+
+--- The `Result` helpers (`ok`, `err`, `is`, `of`, `capture`), so a game can
+--- build library-shaped results in its own wrappers. `result.err` only accepts
+--- an `Error`, so a malformed result cannot be fabricated with it.
+dataforge.result = result
+
 dataforge.hooks = {
 	memory = memory_hook,
 	roblox = roblox_hook,

package/src/profile/common.luau

@@ -90,6 +90,18 @@ function common.is_outdated(record: types.DataRecord?, config: types.ResolvedCon
 	return #record.migrations > #config.migrations
 end
 
+function common.run_predicate(config: types.ResolvedConfig, key: string, data: any): (boolean, any?)
+	local predicate = config.predicate
+	if predicate == nil then
+		return true, nil
+	end
+	local ok, passed = pcall(predicate, data, key)
+	if not ok then
+		return false, passed
+	end
+	return not not passed, nil
+end
+
 --- Rethrows a failed `apply_migrations` with the profile attached to an
 --- `outdated` error (a `migration_mismatch` has no profile field).
 function common.raise_migrations(profile: ProfileBase, migrated: MigrationsResult)
@@ -100,7 +112,9 @@ function common.raise_migrations(profile: ProfileBase, migrated: MigrationsResul
 	error(err, 0)
 end
 
-function common.is_lock_owned(record: types.DataRecord?, job_id: string)
+--- Whether `lock_id` (the id of one acquisition) is the lock currently on
+--- the record, so this acquisition may write it.
+function common.is_lock_owned(record: types.DataRecord?, lock_id: string)
 	if not record then
 		return false
 	end
@@ -110,10 +124,12 @@ function common.is_lock_owned(record: types.DataRecord?, job_id: string)
 		return false
 	end
 
-	return lock.id == job_id
+	return lock.id == lock_id
 end
 
-function common.is_locked_for(record: types.DataRecord?, job_id: string, now: number)
+--- Whether a live lock of another acquisition holds the record, in which case
+--- `lock_id` must wait it out or steal it once it expires.
+function common.is_locked_for(record: types.DataRecord?, lock_id: string, now: number)
 	if not record then
 		return false
 	end
@@ -122,7 +138,7 @@ function common.is_locked_for(record: types.DataRecord?, job_id: string, now: nu
 		return false
 	end
 
-	return lock.id ~= job_id and lock.expires > now
+	return lock.id ~= lock_id and lock.expires > now
 end
 
 function common.has_lock(record: types.DataRecord?)

package/src/profile/lockless.luau

@@ -146,8 +146,9 @@ type WriteOptions = types.LocklessWriteOptions
 ---
 --- Throws `lockless_locked` (a live session lock; the profile is closed),
 --- `tx_lock_lost` (closed too), `outdated` (a newer server wrote the record;
---- nothing written), `migration_mismatch`, `roblox`, or whatever a queued
---- dispatcher / migration threw.
+--- nothing written), `predicate_failed` (the store's predicate rejected the
+--- stored data; nothing written), `migration_mismatch`, `roblox`, or whatever
+--- a queued dispatcher / migration threw.
 local function write_queued(self: LocklessProfile, options: WriteOptions)
 	local config = self.config
 	local scheduler = config._scheduler
@@ -205,6 +206,14 @@ local function write_queued(self: LocklessProfile, options: WriteOptions)
 			return nil
 		end
 
+		-- the store's predicate gates the key: a rejected record is not written
+		-- to, and no `pending` of it is resolved
+		local stored = if old then old.data else nil
+		local passed, predicate_failure = common.run_predicate(config, self.key, stored)
+		if not passed then
+			error(predicate_failure or errors.predicate_failed(self.key, "save", stored, self), 0)
+		end
+
 		-- a `pending` left by some transaction (ours after commit, or another
 		-- server's) decides which data this write builds on
 		local base: any = nil
@@ -341,7 +350,8 @@ end
 --- refreshes the local data with the result. Marks the profile fetched.
 --- Fails (keeping the queue) with `lockless_locked` if another server holds a
 --- live session lock (the profile is closed), `outdated` if the record was
---- already written by a newer server, `migration_mismatch`, `roblox` or
+--- already written by a newer server, `predicate_failed` if the store's
+--- predicate rejected the stored data, `migration_mismatch`, `roblox` or
 --- `profile_closed`. An error thrown by a queued dispatcher propagates as is.
 function lockless_profile.save(self: LocklessProfile): types.Result<nil>
 	return result.capture(function()
@@ -417,7 +427,8 @@ end
 --- Reads the stored record (get_async) into the local data: migrations are
 --- applied, then the queued updates replayed on top, so `get_data()` reflects the
 --- local changes still waiting for a save. Marks the profile fetched. Throws
---- (keeping the queue) if any session lock is on the record. Caller holds the mutex.
+--- (keeping the queue) if any session lock is on the record, or if the store's
+--- predicate rejects the stored data. Caller holds the mutex.
 local function read_record(self: LocklessProfile)
 	local config = self.config
 	local datastore = self._datastore
@@ -433,6 +444,13 @@ local function read_record(self: LocklessProfile)
 	-- a transaction lock does not matter for a read: the data under it is the
 	-- data until that transaction's `pending` lands (handled below)
 
+	local stored = if record then record.data else nil
+	local passed, predicate_failure = common.run_predicate(config, self.key, stored)
+	if not passed then
+		-- nothing is adopted: the profile keeps whatever it had and stays open
+		error(predicate_failure or errors.predicate_failed(self.key, "fetch", stored, self), 0)
+	end
+
 	-- a `pending` on the record: find out whether it committed (the record is
 	-- left as is; the next write folds it in)
 	local base: any = nil
@@ -455,7 +473,8 @@ local function read_record(self: LocklessProfile)
 end
 
 --- Fails with `lockless_locked` (a session lock is on the record; the profile
---- is closed), `outdated` (a newer server wrote the record), `migration_mismatch`,
+--- is closed), `outdated` (a newer server wrote the record), `predicate_failed`
+--- (the store's predicate rejected the stored data), `migration_mismatch`,
 --- `roblox`, `tx_marker_invalid` or `profile_closed`. An error thrown by a
 --- queued dispatcher propagates as is.
 function lockless_profile.fetch(self: LocklessProfile): types.Result<any>

package/src/profile/peek.luau

@@ -1,4 +1,5 @@
 local common = require "./common"
+local errors = require "../errors"
 local result = require "../result"
 local types = require "../types"
 local utils = require "../utils"
@@ -18,13 +19,20 @@ peek_profile.__index = peek_profile
 --- Reads the record with `GetAsync` and adopts it: `lock` and `pending` are
 --- taken as stored, the data gets the declared migrations applied in memory
 --- (nothing is written). A missing key resolves to the template. Throws
---- `roblox`, `outdated` or `migration_mismatch`.
+--- `roblox`, `predicate_failed`, `outdated` or `migration_mismatch`.
 local function read(self: PeekProfile): any
 	local config = self._config
 	local datastore = self._datastore
 
 	local record = utils.get_async(config, datastore, self.key) :: DataRecord?
 
+	-- before anything is adopted: a rejected key leaves the snapshot untouched
+	local stored = if record then record.data else nil
+	local passed, predicate_failure = common.run_predicate(config, self.key, stored)
+	if not passed then
+		error(predicate_failure or errors.predicate_failed(self.key, "peek", stored), 0)
+	end
+
 	self.lock = if record then record.lock else nil
 	self.pending = if record then record.pending else nil
 
@@ -52,15 +60,15 @@ function peek_profile.get_data(self: PeekProfile)
 end
 
 --- Calls `get_async` again and replaces the snapshot. Yields. Fails with
---- `roblox`, `outdated` or `migration_mismatch`, leaving the previous snapshot
---- in place.
+--- `roblox`, `predicate_failed`, `outdated` or `migration_mismatch`, leaving
+--- the previous snapshot in place.
 function peek_profile.refresh(self: PeekProfile): types.Result<any>
 	return result.capture(read, self)
 end
 
 --- Takes the first snapshot right away (yields). The profile has no mutex, no
 --- loops and no hooks: it is a plain value that can be refreshed. Fails with
---- `roblox`, `outdated` or `migration_mismatch`.
+--- `roblox`, `predicate_failed`, `outdated` or `migration_mismatch`.
 function peek_profile.create(options: PeekOptions): types.Result<PeekProfile>
 	local self = {} :: PeekProfile
 	self.kind = "peek"

package/src/profile/profile.luau

@@ -15,12 +15,22 @@ export type LoadOptions = types.LoadOptions
 local profile = {}
 profile.__index = profile
 
-local function adquire_lock(load_options: LoadOptions): types.DataRecord
+--- One counter per process: a lock id must be unique per acquisition, not per
+--- server, so two sessions of the same key on this server can tell their locks
+--- apart. `#` keeps them out of the transaction id namespace (`{job_id}-{n}`),
+--- which lockless writes compare by id.
+local lock_counter = utils.counter()
+
+--- Takes the session lock on `key`, waiting out (or stealing by expiry) any
+--- holder. Returns the locked record and the id this acquisition stamped on it.
+local function adquire_lock(load_options: LoadOptions): (types.DataRecord, string)
 	local config = load_options.config
 	local user_ids = load_options.user_ids
 	local datastore = load_options._datastore
-	local job_id = config._hook.job_id()
 	local key = load_options.key
+	-- minted once per acquisition, before the loop: waiting may write the lock
+	-- several times and every attempt must stamp the same id
+	local lock_id = `{config._hook.job_id()}#{lock_counter()}`
 
 	local scheduler = config._scheduler
 
@@ -30,6 +40,9 @@ local function adquire_lock(load_options: LoadOptions): types.DataRecord
 	-- set by the transform: the record lists more migrations than this server
 	-- declares, so the lock must not be taken (the write is cancelled)
 	local outdated_migrations: { string }? = nil
+	-- set by the transform: the error the store's predicate rejected the record
+	-- with (or the one the predicate itself threw); the lock is not taken
+	local predicate_error: any = nil
 
 	while true do
 		local now = scheduler.now()
@@ -39,11 +52,20 @@ local function adquire_lock(load_options: LoadOptions): types.DataRecord
 			key,
 			function(old: types.DataRecord?): types.DataRecord?
 				outdated_migrations = nil
+				predicate_error = nil
 				if common.is_outdated(old, config) then
 					outdated_migrations = (old :: types.DataRecord).migrations
 					return nil
 				end
-				if common.is_locked_for(old :: types.DataRecord, job_id, now) then
+				-- before the lock check on purpose: a key this server must not
+				-- own is rejected right away instead of waiting out its holder
+				local stored = if old then old.data else nil
+				local passed, failure = common.run_predicate(config, key, stored)
+				if not passed then
+					predicate_error = failure or errors.predicate_failed(key, "load", stored)
+					return nil
+				end
+				if common.is_locked_for(old :: types.DataRecord, lock_id, now) then
 					return nil
 				end
 				local record: types.DataRecord = old or {} :: types.DataRecord
@@ -53,7 +75,7 @@ local function adquire_lock(load_options: LoadOptions): types.DataRecord
 					pending = record.pending,
 					migrations = record.migrations or {},
 					lock = {
-						id = job_id,
+						id = lock_id,
 						expires = now + config.lock_ttl,
 					},
 				}
@@ -64,8 +86,11 @@ local function adquire_lock(load_options: LoadOptions): types.DataRecord
 		if outdated_migrations ~= nil then
 			error(errors.outdated(key, outdated_migrations, common.all_migration_names(config.migrations)), 0)
 		end
-		if common.is_lock_owned(lock_applied, job_id) then
-			return lock_applied
+		if predicate_error ~= nil then
+			error(predicate_error, 0)
+		end
+		if common.is_lock_owned(lock_applied, lock_id) then
+			return lock_applied, lock_id
 		end
 		last_lock = if lock_applied then lock_applied.lock else nil
 
@@ -78,7 +103,7 @@ local function adquire_lock(load_options: LoadOptions): types.DataRecord
 			local current = utils.get_async(config, datastore, key) :: types.DataRecord?
 			last_lock = if current then current.lock else nil
 
-			if not common.is_locked_for(current, job_id, scheduler.now()) then
+			if not common.is_locked_for(current, lock_id, scheduler.now()) then
 				break
 			end
 		end
@@ -130,6 +155,18 @@ local function set_data(self: Profile, data: any)
 	fire_hooks(self, self._hooks.change, new, old)
 end
 
+--- Lets the store drop the key as soon as the profile stops being usable,
+--- without waiting for the final write to land. Idempotent: a lost lock
+--- followed by an unload must only detach once.
+local function detach(self: Profile)
+	local on_detach = self._on_detach
+	if on_detach == nil or self._detached then
+		return
+	end
+	self._detached = true
+	on_detach()
+end
+
 --- Another server took the key: the profile closes without a release write.
 --- Runs inside a write (mutex held by the caller), so it only closes the mutex:
 --- the holder finishes, everything waiting on it is rejected.
@@ -138,6 +175,7 @@ local function process_lock_lost(self: Profile)
 		return
 	end
 	self.open = false
+	detach(self)
 	self._mutex:close(errors.profile_closed(self, "lock_lost"))
 	fire_hooks(self, self._hooks.lock_lost)
 	fire_hooks(self, self._hooks.closed)
@@ -151,23 +189,37 @@ type WriteOptions = {
 --- Writes the data (and `pending`, if any) under our session lock, refreshing
 --- or releasing it. Returns true when written; false and the lock now on the
 --- record (nil when none) when the lock is not ours any more, in which case
---- the profile is closed. Throws a `roblox` error when storage fails.
+--- the profile is closed. Throws a `roblox` error when storage fails, or
+--- `predicate_failed` when the store's predicate rejected the stored data
+--- (nothing is written and the lock is kept).
 local function write_data_record(self: Profile, options: WriteOptions): (boolean, types.Lock?)
 	local config = self.config
 	local scheduler = config._scheduler
 	local datastore = self._datastore
 	local now = scheduler.now()
-	local job_id = config._hook.job_id()
+	-- this acquisition's id, not the job id: another session of this key on this
+	-- server holds a different lock and must not be written over
+	local lock_id = self.lock_id
 
 	-- set by the transform: whether the write went through (the transform may
 	-- run more than once when the storage retries it), and the lock it found
 	local applied = false
 	local seen_lock: types.Lock? = nil
+	-- set by the transform: the store's predicate rejected the stored data (or
+	-- threw); the write is cancelled without the lock being lost
+	local predicate_error: any = nil
 
 	local function transform(old: any?): DataRecord?
 		applied = false
+		predicate_error = nil
 		seen_lock = if old then old.lock else nil
-		if not common.is_lock_owned(old, job_id) then
+		if not common.is_lock_owned(old, lock_id) then
+			return nil
+		end
+		local stored = if old then old.data else nil
+		local passed, failure = common.run_predicate(config, self.key, stored)
+		if not passed then
+			predicate_error = failure or errors.predicate_failed(self.key, "save", stored, self)
 			return nil
 		end
 		applied = true
@@ -175,7 +227,9 @@ local function write_data_record(self: Profile, options: WriteOptions): (boolean
 		local new_lock: types.Lock? = nil
 		if not options.release then
 			new_lock = {
-				id = job_id,
+				-- the same id every time: a fresh one would look like a new lock
+				-- to everyone else
+				id = lock_id,
 				expires = now + config.lock_ttl,
 				tx = nil,
 			} :: types.Lock
@@ -202,6 +256,12 @@ local function write_data_record(self: Profile, options: WriteOptions): (boolean
 		error(err, 0)
 	end
 
+	if predicate_error ~= nil then
+		-- the predicate cancelled the write, not a lost lock: the profile keeps
+		-- its lock and stays open, so the next save may go through again
+		error(predicate_error, 0)
+	end
+
 	if not applied then
 		-- the transform bailed out: the lock is not ours any more
 		process_lock_lost(self)
@@ -222,16 +282,16 @@ local function write_data_record(self: Profile, options: WriteOptions): (boolean
 	return true
 end
 
---- Gives the lock taken by `adquire_lock` back, leaving the record otherwise
---- untouched. Used when the load fails after locking; a failure here is only
---- warned about (the lock expires on its own).
-local function release_lock(load_options: LoadOptions)
+--- Gives the lock `lock_id` (taken by `adquire_lock`) back, leaving the record
+--- otherwise untouched. Used when the load fails after locking; a failure here
+--- is only warned about (the lock expires on its own). Takes the acquisition id
+--- so a failed load cannot clear a lock another local acquisition just took.
+local function release_lock(load_options: LoadOptions, lock_id: string)
 	local config = load_options.config
-	local job_id = config._hook.job_id()
 
 	local ok, err = utils.try(function()
 		utils.update_async(config, load_options._datastore, load_options.key, function(old: DataRecord?): DataRecord?
-			if not common.is_lock_owned(old, job_id) then
+			if not common.is_lock_owned(old, lock_id) then
 				return nil
 			end
 			local record = old :: DataRecord
@@ -298,8 +358,8 @@ end
 
 --- Takes the session lock and resolves the locked record into data. If the
 --- resolution fails the lock is given back before rethrowing.
-local function adquire_and_resolve(load_options: LoadOptions): (any, { string }, boolean)
-	local record = adquire_lock(load_options)
+local function adquire_and_resolve(load_options: LoadOptions): (any, { string }, boolean, string)
+	local record, lock_id = adquire_lock(load_options)
 	local config = load_options.config
 
 	-- from here on the key is locked: anything failing must give it back
@@ -309,10 +369,10 @@ local function adquire_and_resolve(load_options: LoadOptions): (any, { string },
 		config._hook.warn(
 			`datastore: load of "{load_options.key}" failed after taking its lock, releasing it: {tostring(err)}`
 		)
-		release_lock(load_options)
+		release_lock(load_options, lock_id)
 		error(err, 0)
 	end
-	return data, new_migrations, dirty
+	return data, new_migrations, dirty, lock_id
 end
 
 local function load_options_of(self: Profile): LoadOptions
@@ -331,7 +391,7 @@ local function assert_locked(self: Profile)
 end
 
 function profile.load(load_options: LoadOptions): Profile
-	local data, new_migrations, dirty = adquire_and_resolve(load_options)
+	local data, new_migrations, dirty, lock_id = adquire_and_resolve(load_options)
 	local config = load_options.config
 
 	local self: Profile = {} :: any
@@ -341,6 +401,8 @@ function profile.load(load_options: LoadOptions): Profile
 	self._datastore = load_options._datastore
 	self.open = true
 	self.is_locked = true
+	self.lock_id = lock_id
+	self._detached = false
 
 	self.config = load_options.config
 	self.migrations = new_migrations
@@ -416,8 +478,9 @@ function profile.on_lock_lost(self: Profile, callback: () -> ())
 end
 
 --- Writes the data, refreshing the session lock. Fails with `profile_closed`,
---- `released`, `roblox`, or `lock_lost` (another server took the key; the
---- profile is closed).
+--- `released`, `roblox`, `predicate_failed` (the store's predicate rejected
+--- the stored data; nothing is written and the lock is kept), or `lock_lost`
+--- (another server took the key; the profile is closed).
 function profile.save(self: Profile): types.Result<nil>
 	return result.capture(function()
 		common.assert_open(self)
@@ -441,8 +504,8 @@ end
 --- Writes the data and gives the session lock back. The profile stays open
 --- (another server may load the key meanwhile); `update` and `save` fail with
 --- `released` until `readquire`. No-op when already released. Fails with
---- `profile_closed`, `roblox` (the lock stays on the record, `is_locked`
---- stays true) or `lock_lost` (the profile is closed).
+--- `profile_closed`, `roblox` or `predicate_failed` (the lock stays on the
+--- record, `is_locked` stays true), or `lock_lost` (the profile is closed).
 function profile.release(self: Profile): types.Result<nil>
 	return result.capture(function()
 		common.assert_open(self)
@@ -468,8 +531,8 @@ end
 --- Takes the session lock again, waiting for a holder like `load` does, and
 --- adopts the stored record (resolved pending, migrations) as the current
 --- data. Fails with `timeout` (the profile stays open and released),
---- `profile_closed`, `roblox`, `outdated`, `migration_mismatch` or `tx_marker_invalid`. No-op when
---- already locked.
+--- `profile_closed`, `roblox`, `outdated`, `predicate_failed`,
+--- `migration_mismatch` or `tx_marker_invalid`. No-op when already locked.
 function profile.readquire(self: Profile): types.Result<nil>
 	return result.capture(function()
 		common.assert_open(self)
@@ -481,7 +544,7 @@ function profile.readquire(self: Profile): types.Result<nil>
 			if self.is_locked then
 				return
 			end
-			local ok, data, new_migrations, dirty = pcall(adquire_and_resolve, load_options_of(self))
+			local ok, data, new_migrations, dirty, lock_id = pcall(adquire_and_resolve, load_options_of(self))
 			if not ok then
 				local err: any = data
 				if errors.is(err) and err.type == "outdated" then
@@ -491,6 +554,9 @@ function profile.readquire(self: Profile): types.Result<nil>
 			end
 
 			self.migrations = new_migrations
+			-- a fresh acquisition, so a fresh id (the released profile kept the
+			-- old one; nothing could be written with it while released)
+			self.lock_id = lock_id
 			set_data(self, data)
 			self._dirty = dirty
 			self.last_write = self.config._scheduler.now()
@@ -511,6 +577,9 @@ function profile.unload(self: Profile)
 	end
 
 	self.open = false
+	-- before the release write (which may take seconds under throttling): the
+	-- key is free to be loaded again, the new load waits on the record lock
+	detach(self)
 	self._mutex:lock()
 	self._mutex:close(errors.profile_closed(self, "unloaded"))
 	local ok, err = utils.try(function()

package/src/store.luau

@@ -48,8 +48,9 @@ export type Store<T = any> = {
 	config: ResolvedConfig<T>,
 	--- Takes the session lock for `key` and loads it. Yields. Fails with
 	--- `store_closed`, `already_loaded`, `timeout`, `roblox`, `outdated` (a
-	--- newer server wrote the record; no lock is taken), `migration_mismatch`
-	--- or `tx_marker_invalid`.
+	--- newer server wrote the record; no lock is taken), `predicate_failed`
+	--- (`config.predicate` rejected the stored data; no lock is taken),
+	--- `migration_mismatch` or `tx_marker_invalid`.
 	load: (self: Store<T>, key: string, user_ids: { number }) -> Result<Profile<T>>,
 	--- Returns the profile for `key`, waiting for it to load or loading it if
 	--- nobody has yet. Waiters get the same Result as the load.
@@ -63,8 +64,8 @@ export type Store<T = any> = {
 
 	--- Read-only snapshot of `key` via `GetAsync`: the current data and lock.
 	--- Yields. The result is not tracked by the store, takes no lock and cannot
-	--- join a transaction. Fails with `store_closed`, `roblox`, `outdated` or
-	--- `migration_mismatch`.
+	--- join a transaction. Fails with `store_closed`, `roblox`, `outdated`,
+	--- `predicate_failed` or `migration_mismatch`.
 	peek: (self: Store<T>, key: string) -> Result<PeekProfile<T>>,
 
 	--- Atomically updates profiles of this store (locked or lockless). `transform`
@@ -79,6 +80,8 @@ export type Store<T = any> = {
 		config: types.TransactionConfig?
 	) -> Result<boolean>,
 
+	--- Fires for every data change of every profile of this store, including
+	--- the data a key loads with (`old == nil` marks that initial value).
 	on_change: (self: Store<T>, callback: (profile: Profile<T>, new: T, old: T?) -> ()) -> (),
 	on_save: (self: Store<T>, callback: (profile: Profile<T>) -> ()) -> (),
 	on_closing: (self: Store<T>, callback: (profile: Profile<T>) -> ()) -> (),
@@ -113,6 +116,9 @@ local function insert_loaded_lock(self: Store, key: string)
 	table.insert(waiters, thread)
 end
 
+--- Drops `profile` from the registry, unless the key has already been taken by
+--- a newer one: with instant detach a new profile may be registered while the
+--- old one is still writing, and the old one's late unregister must not evict it.
 local function unregister_profile(self: Store, profile: Profile)
 	local key = profile.key
 	if self.profiles[key] == profile then
@@ -158,6 +164,10 @@ function store.create<T>(config: Config<T>): Store<T>
 	assert(type(config) == "table", "datastore: config must be a table")
 	assert(type(config.name) == "string" and #config.name > 0, "datastore: config.name is required")
 	assert(config.template ~= nil, "datastore: config.template is required")
+	assert(
+		config.predicate == nil or type(config.predicate) == "function",
+		"datastore: config.predicate must be a function"
+	)
 
 	local lock_ttl = config.lock_ttl or 60
 	local hook = config._hook
@@ -181,6 +191,7 @@ function store.create<T>(config: Config<T>): Store<T>
 		_scheduler = scheduler,
 
 		migrations = config.migrations or {},
+		predicate = config.predicate,
 
 		autosave_interval = config.autosave_interval or 30,
 		flush_interval = config.flush_interval or config.autosave_interval or 30,
@@ -219,7 +230,10 @@ function store.load(self: Store, key: string, user_ids: { number }): Result<Prof
 	if self.closed then
 		return result.err(errors.store_closed(self))
 	end
-	if self.profiles[key] ~= nil or self._loading[key] then
+	-- a closing profile detaches before its final write, so it is normally gone
+	-- from the registry already; the `open` check is belt and braces
+	local existing = self.profiles[key]
+	if (existing ~= nil and existing.open) or self._loading[key] then
 		return result.err(errors.already_loaded(self, key))
 	end
 	self._loading[key] = true
@@ -252,12 +266,24 @@ function store.load(self: Store, key: string, user_ids: { number }): Result<Prof
 		return failure
 	end
 
+	-- dropped from the registry the moment it stops being usable, so the key can
+	-- be loaded again while the old session's final write is still in flight
+	loaded._on_detach = function()
+		unregister_profile(self, loaded)
+	end
+	-- safety net: a profile that closes some other way still unregisters
 	loaded:on_closed(function()
 		unregister_profile(self, loaded)
 	end)
 	forward_hooks(self, loaded)
 
 	self.profiles[key] = loaded
+	-- a load's initial data never reaches the profile's own hooks (they are
+	-- attached after `profile.load` set it), so report it here: `old == nil`
+	-- marks a key that just appeared. Lockless profiles need no equivalent:
+	-- `get_lockless` forwards their hooks before any `fetch` sets data.
+	fire_hooks(self, self._hooks.change, loaded, loaded:get_data(), nil)
+
 	local success = result.ok(loaded)
 	resume_load_locks(self, key, success)
 	return success
@@ -424,10 +450,21 @@ function store.close(self: Store)
 		end)
 	end
 
+	-- snapshots: `unload` spawns a thread that runs up to its first yield right
+	-- away, and a detaching profile removes itself from these tables
+	local locked: Array<Profile> = {}
 	for _, profile in self.profiles do
-		unload(profile)
+		table.insert(locked, profile)
 	end
+	local lockless: Array<LocklessProfile> = {}
 	for _, profile in self.lockless_profiles do
+		table.insert(lockless, profile)
+	end
+
+	for _, profile in locked do
+		unload(profile)
+	end
+	for _, profile in lockless do
 		unload(profile)
 	end
 	for key in self._loading do

package/src/types.luau

@@ -5,6 +5,17 @@ export type Counter = () -> number
 --- Returns the new data, or nil / false to leave it untouched.
 export type DataDispatcher<T> = (T) -> (T | false)?
 
+--- Decides whether this server may work with a key at all. `data` is the raw
+--- stored data as it is in storage: nil when the key does not exist yet, and
+--- with the declared migrations *not* applied. Returning false rejects the
+--- operation with a `predicate_failed` error: no lock is taken and nothing is
+--- written.
+---
+--- It runs inside the `update_async` transform, so it must be pure: no
+--- yielding, no storage calls, and no mutation of `data` (it may be retried,
+--- and the data it gets is the record this server is about to write back).
+export type Predicate<T = any> = (data: T?, key: string) -> boolean
+
 --- A storage handle for one named store. Deliberately not shaped like a
 --- Roblox DataStore. All methods throw on failure.
 export type DatastoreHandle = {
@@ -45,6 +56,10 @@ export type Config<T = any> = {
 
 	migrations: Array<Migration>?,
 
+	--- Gate on a key's stored data: every load, save, fetch and peek is
+	--- rejected with `predicate_failed` when it returns false. See `Predicate`.
+	predicate: Predicate<T>?,
+
 	--- seconds, default 30 (locked profiles)
 	autosave_interval: number?,
 	-- seconds, default autosave_interval (lockless profiles)
@@ -77,6 +92,8 @@ export type ResolvedConfig<T = any> = RetryConfig & {
 	_scheduler: Scheduler,
 
 	migrations: Array<Migration>,
+	--- nil when the store declared none (nothing is gated).
+	predicate: Predicate<T>?,
 
 	autosave_interval: number,
 	flush_interval: number,
@@ -115,6 +132,10 @@ export type ResolvedTransactionConfig = RetryConfig & {
 }
 
 export type Lock = {
+	--- Identifies the *acquisition* that holds the lock, not the server:
+	--- `{job_id}#{n}` for a profile's session lock, `{job_id}-{n}` for a
+	--- transaction's. Two sessions of one key on the same server hold
+	--- different ids, so they contend like sessions on different servers do.
 	id: string,
 	expires: number,
 	--- Short-lived lock a transaction takes on a lockless key (see `lock_ttl`
@@ -162,7 +183,8 @@ export type TimeoutError = {
 	type: "timeout",
 	message: string,
 	key: string,
-	--- the last lock seen on the record while waiting
+	--- the last lock seen on the record while waiting; its `id` names the
+	--- acquisition holding it, which may be another session on this server
 	lock: Lock?,
 }
 
@@ -210,6 +232,20 @@ export type OutdatedError = {
 	declared_migrations: Array<string>,
 }
 
+--- The store's `predicate` returned false for a key's stored data: this server
+--- must not work with that key. Nothing is written and no lock is taken.
+export type PredicateFailedError = {
+	type: "predicate_failed",
+	message: string,
+	key: string,
+	--- the operation the predicate rejected
+	op: "load" | "save" | "fetch" | "peek",
+	--- the raw stored data the predicate rejected (nil when the key is empty)
+	data: any,
+	--- the profile the call ran on; nil for `store:load` and `store:peek`
+	profile: any?,
+}
+
 export type NotFetchedError = {
 	type: "not_fetched",
 	message: string,
@@ -275,6 +311,7 @@ export type Error =
 	| LocklessLockedError
 	| TxLockLostError
 	| OutdatedError
+	| PredicateFailedError
 	| NotFetchedError
 	| ProfileClosedError
 	| MigrationMismatchError
@@ -399,7 +436,7 @@ export type ProfileBase<T = any> = {
 	unload: (self: ProfileBase<T>) -> (),
 	--- Ok(true) when the data changed, Ok(false) when the dispatcher returned
 	--- nil / false. An error thrown by the dispatcher propagates as is.
-	update: (self: ProfileBase<T>, (T) -> T | false) -> Result<boolean>,
+	update: (self: ProfileBase<T>, dispatcher: DataDispatcher<T>) -> Result<boolean>,
 
 	on_change: (self: ProfileBase<T>, callback: (new: T, old: T?) -> ()) -> (),
 	on_save: (self: ProfileBase<T>, callback: () -> ()) -> (),
@@ -424,6 +461,9 @@ export type ProfileBase<T = any> = {
 export type Profile<T = any> = ProfileBase<T> & {
 	kind: "locked",
 	last_write: number,
+	--- The id of this acquisition's lock; re-stamped unchanged on every save,
+	--- replaced by `readquire`. See `Lock.id`.
+	lock_id: string,
 	--- Whether the profile currently holds its session lock. True after `load`;
 	--- `release` clears it, `readquire` takes it again. While released,
 	--- `update` / `save` throw and the profile cannot join a transaction.
@@ -450,6 +490,13 @@ export type Profile<T = any> = ProfileBase<T> & {
 	-- internal, used by transactions. Returns false (and the lock now on the
 	-- record) when the lock is gone.
 	_write_record: (self: Profile<T>, options: ProfileWriteOptions) -> (boolean, Lock?),
+
+	--- internal, set by the store: called once, as soon as the profile stops
+	--- being usable (an unload before its final write, or a lost lock), so the
+	--- key can be loaded again without waiting for that write.
+	_on_detach: (() -> ())?,
+	--- internal: whether `_on_detach` has run.
+	_detached: boolean,
 }
 
 export type ProfileWriteOptions = {
@@ -497,6 +544,7 @@ export type PeekProfile<T = any> = {
 	_datastore: DatastoreHandle,
 
 	--- Lock currently on the record (session or transaction), nil when free.
+	--- Its `id` names an acquisition, not a server (see `Lock.id`).
 	lock: Lock?,
 	--- Transaction marker on the record, if any. Left as stored, never resolved.
 	pending: Pending<T>?,