@armoury/fivem-framework-server 1.0.25 → 1.0.27

package/dist/cjs/server/services/session/session.service.js

@@ -19,12 +19,6 @@ let SessionService = class SessionService {
     constructor(armouryResource) {
         this.armouryResource = armouryResource;
     }
-    getClaimValue(sessionId, claimName) {
-        return this.armouryResource.instance.getClaimValue(sessionId, claimName);
-    }
-    setClaim(sessionId, claimName, value) {
-        return this.armouryResource.instance.setClaim(sessionId, claimName, value);
-    }
     getNumPlayersConnected() {
         return this.armouryResource.instance.getNumPlayersConnected();
     }

package/dist/cjs/shared/models/index.js

@@ -19,3 +19,4 @@ __exportStar(require("./character"), exports);
 /** Session */
 __exportStar(require("./session"), exports);
 __exportStar(require("./session-update-type"), exports);
+__exportStar(require("./session-claim"), exports);

package/dist/cjs/shared/models/session-claim.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionClaimType = void 0;
+var SessionClaimType;
+(function (SessionClaimType) {
+    SessionClaimType[SessionClaimType["Direct"] = 0] = "Direct";
+    SessionClaimType[SessionClaimType["Proxied"] = 1] = "Proxied";
+})(SessionClaimType || (exports.SessionClaimType = SessionClaimType = {}));

package/dist/cjs/shared/models/session.js

@@ -1,20 +1,108 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Session = void 0;
+const session_claim_1 = require("./session-claim");
 class Session {
-    constructor(id, platformId, lastKnownName, principal, claims = {}) {
+    constructor(id, platformId, lastKnownName, principal) {
         this.id = id;
         this.platformId = platformId;
         this.lastKnownName = lastKnownName;
         this.principal = principal;
-        this.claims = claims;
     }
-    getClaimValue(claimName) {
+    /**
+     * Gets the public state of a player.
+     *
+     * @param stateItemName the name of the state item to update.
+     * @returns the value from the state, or null if not found.
+     */
+    getState(stateItemName) {
         var _a;
-        return (_a = this.claims[claimName]) !== null && _a !== void 0 ? _a : null;
+        return (_a = Cfx.Player(this.id).state[`session:${stateItemName}:value`]) !== null && _a !== void 0 ? _a : null;
     }
-    setClaim(claimName, value) {
-        this.claims[claimName] = value;
+    /**
+     * Updates the state of a player.
+     *
+     * **`⚠️ Warning:`** If your intention is to save data which should NOT be accessible to the
+     * client, please use `setServerClaim` instead.
+     *
+     * ---
+     *
+     * In a client script, this will always be the replicated value set by the server.
+     * In a server script, this will update the state for that player.
+     *
+     * @param stateItemName the name of the state item to update.
+     * @param value the value to set to the state.
+     * @param replicate whether to replicate this value. This will always be false in a client script.
+     * @returns the value which has been set.
+     */
+    setState(stateItemName, value, replicate) {
+        Cfx.Player(this.id).state.set(`session:${stateItemName}:value`, value, replicate !== null && replicate !== void 0 ? replicate : Cfx.Server.IsDuplicityVersion());
+        return value;
+    }
+    /**
+     * Gets the state of the player, where the state is data NOT accessible to the client.
+     *
+     * @param claimName the name of the claim/state item to get.
+     * @returns the value from the state, or null if not found.
+     */
+    getServerClaimValue(claimName) {
+        var _a;
+        if (!Cfx.Server.IsDuplicityVersion()) {
+            console.error('Claims are not currently available in client scripts.');
+            return null;
+        }
+        const claimValue = Cfx.Player(this.id).state[`session:${claimName}:value`];
+        if (claimValue == null) {
+            return null;
+        }
+        const kind = (_a = Cfx.Player(this.id).state[`session:${claimName}:kind`]) !== null && _a !== void 0 ? _a : session_claim_1.SessionClaimType.Direct;
+        if (kind === session_claim_1.SessionClaimType.Proxied) {
+            const proxiedValue = this.getProxiedServerClaimValue(claimName);
+            Cfx.Player(this.id).state.set(`session:${claimName}:value`, proxiedValue, false);
+            return proxiedValue;
+        }
+        return this.getState(claimName);
+    }
+    /**
+     * Gets proxied state of a player. This is usually state which doesn't hold
+     * primitive data types (for example, an `item`).
+     *
+     * @param claim the claim object to proxy for.
+     * @returns the value from the proxied state, or null if not found or impossible.
+     */
+    getProxiedServerClaimValue(claimName) {
+        var _a, _b;
+        if (!Cfx.Server.IsDuplicityVersion()) {
+            console.error('Proxied claims are not currently available in client scripts.');
+            return null;
+        }
+        const resource = Cfx.GlobalState[`session:${claimName}:proxy`];
+        if (!resource) {
+            console.error(`There was no proxied claim registered for claim with name ${claimName}, `
+                + 'returning null.');
+            return null;
+        }
+        return (_b = (_a = globalThis.exports[resource]) === null || _a === void 0 ? void 0 : _a.getProxiedClaimValue(claimName, this.id)) !== null && _b !== void 0 ? _b : null;
+    }
+    /**
+     * Updates the state of the player, but doesn't replicate the value to the client.
+     * Useful when you want to have data NOT accessible to the client, on the server.
+     *
+     * @param claimName the name of the claim/state item to update.
+     * @returns the updated value, or null if not found or impossible to update.
+     */
+    setServerClaim(claimName, value) {
+        if (!Cfx.Server.IsDuplicityVersion()) {
+            console.error('Claims are not currently available in client scripts.');
+            return null;
+        }
+        const proxy = Cfx.GlobalState[`session:${claimName}:proxy`];
+        if (proxy != null) {
+            console.error(`Attempting to set value of server claim ${claimName}, but there's a proxy registered `
+                + 'for it. Returning null, and doing nothing.');
+            return null;
+        }
+        this.setState(claimName, value, false);
         return value;
     }
 }

package/dist/esm/server/services/session/session.service.js

@@ -16,12 +16,6 @@ let SessionService = class SessionService {
     constructor(armouryResource) {
         this.armouryResource = armouryResource;
     }
-    getClaimValue(sessionId, claimName) {
-        return this.armouryResource.instance.getClaimValue(sessionId, claimName);
-    }
-    setClaim(sessionId, claimName, value) {
-        return this.armouryResource.instance.setClaim(sessionId, claimName, value);
-    }
     getNumPlayersConnected() {
         return this.armouryResource.instance.getNumPlayersConnected();
     }

package/dist/esm/shared/models/index.js

@@ -3,3 +3,4 @@ export * from './character';
 /** Session */
 export * from './session';
 export * from './session-update-type';
+export * from './session-claim';

package/dist/esm/shared/models/session-claim.js

@@ -0,0 +1,5 @@
+export var SessionClaimType;
+(function (SessionClaimType) {
+    SessionClaimType[SessionClaimType["Direct"] = 0] = "Direct";
+    SessionClaimType[SessionClaimType["Proxied"] = 1] = "Proxied";
+})(SessionClaimType || (SessionClaimType = {}));

package/dist/esm/shared/models/session.js

@@ -1,17 +1,105 @@
+import { SessionClaimType } from './session-claim';
 export class Session {
-    constructor(id, platformId, lastKnownName, principal, claims = {}) {
+    constructor(id, platformId, lastKnownName, principal) {
         this.id = id;
         this.platformId = platformId;
         this.lastKnownName = lastKnownName;
         this.principal = principal;
-        this.claims = claims;
     }
-    getClaimValue(claimName) {
+    /**
+     * Gets the public state of a player.
+     *
+     * @param stateItemName the name of the state item to update.
+     * @returns the value from the state, or null if not found.
+     */
+    getState(stateItemName) {
         var _a;
-        return (_a = this.claims[claimName]) !== null && _a !== void 0 ? _a : null;
+        return (_a = Cfx.Player(this.id).state[`session:${stateItemName}:value`]) !== null && _a !== void 0 ? _a : null;
     }
-    setClaim(claimName, value) {
-        this.claims[claimName] = value;
+    /**
+     * Updates the state of a player.
+     *
+     * **`⚠️ Warning:`** If your intention is to save data which should NOT be accessible to the
+     * client, please use `setServerClaim` instead.
+     *
+     * ---
+     *
+     * In a client script, this will always be the replicated value set by the server.
+     * In a server script, this will update the state for that player.
+     *
+     * @param stateItemName the name of the state item to update.
+     * @param value the value to set to the state.
+     * @param replicate whether to replicate this value. This will always be false in a client script.
+     * @returns the value which has been set.
+     */
+    setState(stateItemName, value, replicate) {
+        Cfx.Player(this.id).state.set(`session:${stateItemName}:value`, value, replicate !== null && replicate !== void 0 ? replicate : Cfx.Server.IsDuplicityVersion());
+        return value;
+    }
+    /**
+     * Gets the state of the player, where the state is data NOT accessible to the client.
+     *
+     * @param claimName the name of the claim/state item to get.
+     * @returns the value from the state, or null if not found.
+     */
+    getServerClaimValue(claimName) {
+        var _a;
+        if (!Cfx.Server.IsDuplicityVersion()) {
+            console.error('Claims are not currently available in client scripts.');
+            return null;
+        }
+        const claimValue = Cfx.Player(this.id).state[`session:${claimName}:value`];
+        if (claimValue == null) {
+            return null;
+        }
+        const kind = (_a = Cfx.Player(this.id).state[`session:${claimName}:kind`]) !== null && _a !== void 0 ? _a : SessionClaimType.Direct;
+        if (kind === SessionClaimType.Proxied) {
+            const proxiedValue = this.getProxiedServerClaimValue(claimName);
+            Cfx.Player(this.id).state.set(`session:${claimName}:value`, proxiedValue, false);
+            return proxiedValue;
+        }
+        return this.getState(claimName);
+    }
+    /**
+     * Gets proxied state of a player. This is usually state which doesn't hold
+     * primitive data types (for example, an `item`).
+     *
+     * @param claim the claim object to proxy for.
+     * @returns the value from the proxied state, or null if not found or impossible.
+     */
+    getProxiedServerClaimValue(claimName) {
+        var _a, _b;
+        if (!Cfx.Server.IsDuplicityVersion()) {
+            console.error('Proxied claims are not currently available in client scripts.');
+            return null;
+        }
+        const resource = Cfx.GlobalState[`session:${claimName}:proxy`];
+        if (!resource) {
+            console.error(`There was no proxied claim registered for claim with name ${claimName}, `
+                + 'returning null.');
+            return null;
+        }
+        return (_b = (_a = globalThis.exports[resource]) === null || _a === void 0 ? void 0 : _a.getProxiedClaimValue(claimName, this.id)) !== null && _b !== void 0 ? _b : null;
+    }
+    /**
+     * Updates the state of the player, but doesn't replicate the value to the client.
+     * Useful when you want to have data NOT accessible to the client, on the server.
+     *
+     * @param claimName the name of the claim/state item to update.
+     * @returns the updated value, or null if not found or impossible to update.
+     */
+    setServerClaim(claimName, value) {
+        if (!Cfx.Server.IsDuplicityVersion()) {
+            console.error('Claims are not currently available in client scripts.');
+            return null;
+        }
+        const proxy = Cfx.GlobalState[`session:${claimName}:proxy`];
+        if (proxy != null) {
+            console.error(`Attempting to set value of server claim ${claimName}, but there's a proxy registered `
+                + 'for it. Returning null, and doing nothing.');
+            return null;
+        }
+        this.setState(claimName, value, false);
         return value;
     }
 }

package/dist/types/server/services/session/session.service.d.ts

@@ -2,8 +2,6 @@ import { ResourceRef, Session } from '@armoury/fivem-framework-common';
 export declare class SessionService {
     private readonly armouryResource;
     constructor(armouryResource: ResourceRef);
-    getClaimValue<T>(sessionId: number, claimName: string): T | null;
-    setClaim<T>(sessionId: number, claimName: string, value: T): T | null;
     getNumPlayersConnected(): number;
     getAllPlayerIds(): number[];
     getAllPlayerPrincipals(): number[];

package/dist/types/shared/models/index.d.ts

@@ -3,3 +3,4 @@ export * from './character';
 /** Session */
 export * from './session';
 export * from './session-update-type';
+export * from './session-claim';

package/dist/types/shared/models/session-claim.d.ts

@@ -0,0 +1,13 @@
+export interface SessionDirectClaim<TVal = unknown> {
+    $kind: SessionClaimType.Direct;
+    cachedValue: TVal;
+}
+export interface SessionProxiedClaim {
+    $kind: SessionClaimType.Proxied;
+    resource: string;
+}
+export type SessionClaim<TVal = unknown> = SessionDirectClaim<TVal> | SessionProxiedClaim;
+export declare enum SessionClaimType {
+    Direct = 0,
+    Proxied = 1
+}

package/dist/types/shared/models/session.d.ts

@@ -1,17 +1,78 @@
 export interface Session {
+    /**
+     * The session ID, which always matches the server ID of a
+     * player.
+     */
     readonly id: number;
+    /**
+     * The platform identifier for this player. Most often, this
+     * will be the FiveM identifier for a player.
+     */
     readonly platformId: string;
+    /**
+     * The name this player has most recently used when logging in.
+     * NEVER trust this value - it can change with every reconnect.
+     */
     readonly lastKnownName: string;
+    /**
+     * The principal of a session. Most often, this will be the
+     * account ID of that player.
+     */
     principal?: number;
-    readonly claims: Record<string, unknown>;
 }
 export declare class Session {
     readonly id: number;
     readonly platformId: string;
     readonly lastKnownName: string;
     principal?: number | undefined;
-    readonly claims: Record<string, unknown>;
-    constructor(id: number, platformId: string, lastKnownName: string, principal?: number | undefined, claims?: Record<string, unknown>);
-    getClaimValue<T>(claimName: string): T | null;
-    setClaim<T>(claimName: string, value: T): T;
+    constructor(id: number, platformId: string, lastKnownName: string, principal?: number | undefined);
+    /**
+     * Gets the public state of a player.
+     *
+     * @param stateItemName the name of the state item to update.
+     * @returns the value from the state, or null if not found.
+     */
+    getState<T>(stateItemName: string): T | null;
+    /**
+     * Updates the state of a player.
+     *
+     * **`⚠️ Warning:`** If your intention is to save data which should NOT be accessible to the
+     * client, please use `setServerClaim` instead.
+     *
+     * ---
+     *
+     * In a client script, this will always be the replicated value set by the server.
+     * In a server script, this will update the state for that player.
+     *
+     * @param stateItemName the name of the state item to update.
+     * @param value the value to set to the state.
+     * @param replicate whether to replicate this value. This will always be false in a client script.
+     * @returns the value which has been set.
+     */
+    setState<T extends Primitive>(stateItemName: string, value: T, replicate?: boolean): T | null;
+    /**
+     * Gets the state of the player, where the state is data NOT accessible to the client.
+     *
+     * @param claimName the name of the claim/state item to get.
+     * @returns the value from the state, or null if not found.
+     */
+    getServerClaimValue<T>(claimName: string): T | null;
+    /**
+     * Gets proxied state of a player. This is usually state which doesn't hold
+     * primitive data types (for example, an `item`).
+     *
+     * @param claim the claim object to proxy for.
+     * @returns the value from the proxied state, or null if not found or impossible.
+     */
+    private getProxiedServerClaimValue;
+    /**
+     * Updates the state of the player, but doesn't replicate the value to the client.
+     * Useful when you want to have data NOT accessible to the client, on the server.
+     *
+     * @param claimName the name of the claim/state item to update.
+     * @returns the updated value, or null if not found or impossible to update.
+     */
+    setServerClaim<T extends Primitive>(claimName: string, value: T): T | null;
 }
+type Primitive = string | number | boolean | bigint | symbol | null | undefined;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@armoury/fivem-framework-server",
-  "version": "1.0.25",
+  "version": "1.0.27",
   "description": "Server APIs for the Armoury FiveM framework",
   "main": "dist/cjs/server/index.js",
   "module": "dist/esm/server/index.js",
@@ -27,7 +27,7 @@
     "rxjs": "^7.8.1"
   },
   "peerDependencies": {
-    "@armoury/fivem-framework-common": "1.0.25"
+    "@armoury/fivem-framework-common": "1.0.27"
   },
   "publishConfig": {
     "access": "public"