@rbxts/dataforge 0.1.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;
 		/**
@@ -197,6 +232,188 @@ declare namespace dataforge {
 
 	type TxOutcome = "committed" | "aborted";
 
+	/*
+		Errors and results
+	*/
+
+	interface ErrorBase {
+		readonly type: string;
+		/** Human readable; `tostring(err)` returns it. */
+		readonly message: string;
+	}
+
+	/** Storage kept failing after `retry_attempts`. */
+	interface RobloxError extends ErrorBase {
+		readonly type: "roblox";
+		readonly op: "get_async" | "update_async";
+		readonly store: string;
+		readonly key: string;
+		/** The last raw error the storage hook threw. */
+		readonly cause: unknown;
+	}
+
+	/** `load` / `readquire` gave up after `load_timeout`. */
+	interface TimeoutError extends ErrorBase {
+		readonly type: "timeout";
+		readonly key: string;
+		/** The last lock seen on the record (its holder). */
+		readonly lock: Lock | undefined;
+	}
+
+	/** A write found the session lock is not ours; the profile is closed. */
+	interface LockLostError extends ErrorBase {
+		readonly type: "lock_lost";
+		readonly profile: Profile<any>;
+		/** The lock now on the record, `undefined` when it was wiped. */
+		readonly lock: Lock | undefined;
+	}
+
+	/** The profile was released and not readquired. */
+	interface ReleasedError extends ErrorBase {
+		readonly type: "released";
+		readonly profile: Profile<any>;
+	}
+
+	/** Another server holds a live session lock on a lockless key; the profile is closed. */
+	interface LocklessLockedError extends ErrorBase {
+		readonly type: "lockless_locked";
+		readonly profile: LocklessProfile<any>;
+		readonly lock: Lock;
+	}
+
+	/** The transaction lock a lockless participant held is gone or replaced; the profile is closed. */
+	interface TxLockLostError extends ErrorBase {
+		readonly type: "tx_lock_lost";
+		readonly profile: LocklessProfile<any>;
+		/** The transaction lock this profile held. */
+		readonly expected: Lock;
+		/** The lock now on the record, `undefined` when none. */
+		readonly lock: Lock | undefined;
+	}
+
+	/**
+	 * The record was written by a newer server (it lists more migrations than
+	 * this store declares). Nothing is written and no lock is taken.
+	 */
+	interface OutdatedError extends ErrorBase {
+		readonly type: "outdated";
+		readonly key: string;
+		/** The profile the call ran on; `undefined` for `store.load` and `store.peek`. */
+		readonly profile: AnyProfile<any> | undefined;
+		readonly record_migrations: string[];
+		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";
+		readonly profile: LocklessProfile<any>;
+	}
+
+	/** The profile is closed (or closed while the call waited for it). */
+	interface ProfileClosedError extends ErrorBase {
+		readonly type: "profile_closed";
+		readonly profile: AnyProfile<any>;
+		readonly reason: "unloaded" | "lock_lost";
+	}
+
+	/**
+	 * A name in the record's applied migrations differs from the declared one
+	 * at `index`. A record with more migrations than declared is `outdated`.
+	 */
+	interface MigrationMismatchError extends ErrorBase {
+		readonly type: "migration_mismatch";
+		readonly key: string;
+		readonly index: number;
+		readonly expected: string;
+		readonly actual: string;
+		/** Names the record has applied / this store declares. */
+		readonly applied: string[];
+		readonly declared: string[];
+	}
+
+	/** The transaction aborted. */
+	interface TxAbortedError extends ErrorBase {
+		readonly type: "tx_aborted";
+		readonly id: string;
+		/**
+		 * The error of the participant that failed phase 1; `undefined` when
+		 * the marker was already resolved as aborted by another server.
+		 */
+		readonly cause: DataforgeError | undefined;
+	}
+
+	/** The marker datastore holds something other than "committed" / "aborted". */
+	interface TxMarkerInvalidError extends ErrorBase {
+		readonly type: "tx_marker_invalid";
+		readonly id: string;
+		readonly value: unknown;
+	}
+
+	interface StoreClosedError extends ErrorBase {
+		readonly type: "store_closed";
+		readonly store: Store<any>;
+	}
+
+	interface AlreadyLoadedError extends ErrorBase {
+		readonly type: "already_loaded";
+		readonly store: Store<any>;
+		readonly key: string;
+	}
+
+	/** Every runtime failure the library reports. Narrow on `type`. */
+	type DataforgeError =
+		| RobloxError
+		| TimeoutError
+		| LockLostError
+		| ReleasedError
+		| LocklessLockedError
+		| TxLockLostError
+		| OutdatedError
+		| PredicateFailedError
+		| NotFetchedError
+		| ProfileClosedError
+		| MigrationMismatchError
+		| TxAbortedError
+		| TxMarkerInvalidError
+		| StoreClosedError
+		| AlreadyLoadedError;
+
+	interface Ok<T> {
+		readonly success: true;
+		readonly value: T;
+		/** Returns `value`. */
+		unwrap(): T;
+	}
+
+	interface Err {
+		readonly success: false;
+		readonly error: DataforgeError;
+		/** Throws `error` (the table itself). */
+		unwrap(): never;
+	}
+
+	/**
+	 * What every fallible call returns. Programmer errors (bad config, misuse
+	 * of a transaction) and errors thrown by your own callbacks still throw.
+	 */
+	type Result<T> = Ok<T> | Err;
+
 	/*
 		Profiles
 	*/
@@ -216,16 +433,25 @@ declare namespace dataforge {
 		readonly open: boolean;
 		readonly migrations: string[];
 
-		/** Current data. Throws if the profile is closed or (lockless) not fetched. */
+		/**
+		 * Current data. A plain accessor: throws a `DataforgeError`
+		 * (`profile_closed`, or `not_fetched` for a lockless profile).
+		 */
 		get_data(): T;
-		save(): void;
+		/**
+		 * Fails with `profile_closed`, `released`, `roblox`, `predicate_failed`,
+		 * `lock_lost` (locked) or `lockless_locked`, `outdated`, ... (lockless).
+		 */
+		save(): Result<void>;
 		unload(): void;
 		/**
 		 * Applies `dispatcher` to the current data. Returning `undefined` or
-		 * `false` leaves the data untouched (returns `false`); anything else
-		 * becomes the new data and is persisted on the next save.
+		 * `false` leaves the data untouched (`Ok(false)`); anything else
+		 * becomes the new data and is persisted on the next save (`Ok(true)`).
+		 * Fails with `profile_closed` / `released`; an error thrown by the
+		 * dispatcher propagates as is.
 		 */
-		update(dispatcher: DataDispatcher<T>): boolean;
+		update(dispatcher: DataDispatcher<T>): Result<boolean>;
 
 		on_change(callback: (newData: T, oldData: T | undefined) => void): void;
 		on_save(callback: () => void): void;
@@ -252,11 +478,16 @@ 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
-		 * released, `update` / `save` throw and the profile cannot join a
-		 * transaction.
+		 * released, `update` / `save` fail with `released` and the profile
+		 * cannot join a transaction.
 		 */
 		readonly is_locked: boolean;
 
@@ -266,13 +497,16 @@ 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`, `predicate_failed` or `lock_lost`.
 		 */
-		release(): void;
+		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.
+		 * stored record as the current data. No-op when already locked. Fails
+		 * with `timeout`, `profile_closed`, `roblox`, `outdated`,
+		 * `predicate_failed`, `migration_mismatch`.
 		 */
-		readquire(): void;
+		readquire(): Result<void>;
 	}
 
 	/** Profile without a session lock; updates are queued and folded into storage on save. */
@@ -286,9 +520,11 @@ 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. Throws (keeping the queue) if a session lock is on the record.
+		 * Yields. Fails (keeping the queue) with `lockless_locked` if a session
+		 * lock is on the record, `outdated`, `predicate_failed`, `roblox`,
+		 * `migration_mismatch`, `profile_closed`.
 		 */
-		fetch(): T;
+		fetch(): Result<T>;
 	}
 
 	/** Either profile kind; narrow on `kind`. */
@@ -310,8 +546,12 @@ declare namespace dataforge {
 		readonly migrations: string[];
 
 		get_data(): T;
-		/** Calls `GetAsync` again and replaces `lock`, `pending`, `migrations` and the data. Yields. */
-		refresh(): T;
+		/**
+		 * Calls `GetAsync` again and replaces `lock`, `pending`, `migrations`
+		 * and the data. Yields. Fails with `roblox`, `predicate_failed`,
+		 * `outdated` or `migration_mismatch`, keeping the previous snapshot.
+		 */
+		refresh(): Result<T>;
 	}
 
 	/*
@@ -334,37 +574,57 @@ declare namespace dataforge {
 		readonly profiles: ReadonlyMap<string, Profile<T>>;
 		readonly lockless_profiles: ReadonlyMap<string, LocklessProfile<T>>;
 
-		/** Takes the session lock for `key` and loads it. Yields. Throws when already loaded. */
-		load(key: string, user_ids: number[]): Profile<T>;
-		/** Returns the profile for `key`, waiting for it to load or loading it if nobody has yet. */
-		wait_loaded(key: string, user_ids: number[]): Profile<T>;
+		/**
+		 * 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>>;
+		/**
+		 * 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.
+		 */
+		wait_loaded(key: string, user_ids: number[]): Result<Profile<T>>;
 		get_loaded(key: string): Profile<T> | undefined;
 
 		/**
 		 * Returns the lockless profile for `key`, creating it if needed. Never
 		 * yields: a lockless profile does no storage work until `fetch`.
+		 * Throws a `store_closed` error on a closed store.
 		 */
 		get_lockless(key: string, user_ids: number[]): LocklessProfile<T>;
 
 		/**
 		 * 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.
+		 * cannot join a transaction. Fails with `store_closed`, `roblox`,
+		 * `outdated`, `predicate_failed` or `migration_mismatch`.
 		 */
-		peek(key: string): PeekProfile<T>;
+		peek(key: string): Result<PeekProfile<T>>;
 
 		/**
 		 * Atomically updates profiles of this store (locked or lockless).
 		 * `transform` gets their data in order and returns the new data in the
-		 * same order, or `false` to cancel. Returns `false` when cancelled,
-		 * `true` when committed; throws when aborted.
+		 * same order, or `false` to cancel. `Ok(false)` when cancelled,
+		 * `Ok(true)` when committed; fails like `dataforge.transaction`, plus
+		 * `store_closed`.
 		 */
 		transaction(
 			profiles: ProfileBase<T>[],
 			transform: (data: T[]) => T[] | false,
 			config?: TransactionConfig,
-		): boolean;
+		): 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;
@@ -390,14 +650,40 @@ declare namespace dataforge {
 	 * and lockless ones. `process` reads with `ctx.get(profile)` and stages
 	 * writes with `ctx.set(profile, newData)`; return `false` to cancel.
 	 *
-	 * Returns `false` when cancelled, `true` when committed. Throws when aborted.
-	 * `config` defaults its retry settings to the first profile's.
+	 * `Ok(false)` when cancelled, `Ok(true)` when committed. Fails with
+	 * `tx_aborted` (see its `cause`), `profile_closed`, `released`, or what
+	 * flushing a lockless participant raised. Misuse and errors thrown by
+	 * `process` throw. `config` defaults its retry settings to the first
+	 * profile's.
 	 */
 	function transaction(
 		profiles: ProfileBase<any>[],
 		process: (ctx: TxContext) => boolean | undefined,
 		config?: TransactionConfig,
-	): boolean;
+	): 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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rbxts/dataforge",
-  "version": "0.1.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"
   }
 }