@aifivem/lib 0.6.0 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +3 -3
- package/src/client/action.ts +38 -38
- package/src/client/callback.ts +70 -70
- package/src/client/controls.ts +73 -73
- package/src/client/entity.ts +15 -15
- package/src/client/headshot.ts +26 -26
- package/src/client/index.ts +2 -5
- package/src/client/localPed.ts +169 -169
- package/src/client/location.ts +54 -54
- package/src/client/netEvent.ts +40 -40
- package/src/client/nuiScreen.ts +87 -87
- package/src/client/phone.ts +14 -0
- package/src/client/players.ts +34 -34
- package/src/client/raycast.ts +48 -48
- package/src/client/shot.ts +29 -29
- package/src/client/vehicleProps.ts +107 -107
- package/src/fivem/callbackNames.ts +12 -12
- package/src/fivem/locale.ts +57 -57
- package/src/server/callback.ts +112 -112
- package/src/server/characters.ts +12 -3
- package/src/server/dataFile.ts +81 -81
- package/src/server/illegal.ts +26 -0
- package/src/server/index.ts +2 -0
- package/src/server/mdt.ts +13 -0
- package/src/server/netEvent.ts +58 -58
- package/src/server/phone.ts +11 -5
- package/src/server/position.ts +20 -20
- package/src/server/rateLimit.ts +53 -53
- package/src/server/stress.ts +4 -1
- package/src/server/warrants.ts +37 -0
- package/src/shared/format.ts +26 -26
- package/src/shared/grid.ts +20 -20
- package/src/shared/index.ts +151 -151
- package/src/shared/lang.ts +39 -39
- package/src/shared/read.ts +60 -60
- package/src/shared/strict.ts +70 -70
- package/src/shared/vec.ts +19 -19
- package/src/shared/vehicleProps.ts +138 -138
- package/src/shared/wait.ts +27 -27
package/src/shared/index.ts
CHANGED
|
@@ -1,17 +1,17 @@
|
|
|
1
|
-
/** Helpers usable on client and server. No FiveM natives here. */
|
|
2
|
-
|
|
3
|
-
export { sleep, waitFor } from "./wait";
|
|
4
|
-
export { bool, int, num, record, str, vec4, type Vec4 } from "./read";
|
|
5
|
-
export {
|
|
6
|
-
oneArg,
|
|
7
|
-
readFinite,
|
|
8
|
-
readId,
|
|
9
|
-
readInt,
|
|
10
|
-
readText,
|
|
11
|
-
readVec3,
|
|
12
|
-
readVec4,
|
|
13
|
-
} from "./strict";
|
|
14
|
-
export { fail, isActionOk, replyError, type ActionResult } from "./action";
|
|
1
|
+
/** Helpers usable on client and server. No FiveM natives here. */
|
|
2
|
+
|
|
3
|
+
export { sleep, waitFor } from "./wait";
|
|
4
|
+
export { bool, int, num, record, str, vec4, type Vec4 } from "./read";
|
|
5
|
+
export {
|
|
6
|
+
oneArg,
|
|
7
|
+
readFinite,
|
|
8
|
+
readId,
|
|
9
|
+
readInt,
|
|
10
|
+
readText,
|
|
11
|
+
readVec3,
|
|
12
|
+
readVec4,
|
|
13
|
+
} from "./strict";
|
|
14
|
+
export { fail, isActionOk, replyError, type ActionResult } from "./action";
|
|
15
15
|
export {
|
|
16
16
|
distance,
|
|
17
17
|
flatDistance,
|
|
@@ -20,7 +20,7 @@ export {
|
|
|
20
20
|
type Vec3,
|
|
21
21
|
} from "./vec";
|
|
22
22
|
export { pickRandom, randomInt, rollChance } from "./random";
|
|
23
|
-
export { ServerClock } from "./clock";
|
|
23
|
+
export { ServerClock } from "./clock";
|
|
24
24
|
export {
|
|
25
25
|
formatWeight,
|
|
26
26
|
groupDigits,
|
|
@@ -35,145 +35,145 @@ export {
|
|
|
35
35
|
isPublic,
|
|
36
36
|
readAccess,
|
|
37
37
|
type AccessRule,
|
|
38
|
-
} from "./access";
|
|
39
|
-
export {
|
|
40
|
-
BLIP_STYLE_FIELDS,
|
|
41
|
-
readBlipStyle,
|
|
42
|
-
type BlipStyle,
|
|
43
|
-
} from "./blipStyle";
|
|
44
|
-
export {
|
|
45
|
-
polyFromCorners,
|
|
46
|
-
readZoneShape,
|
|
47
|
-
zoneBounds,
|
|
48
|
-
zoneContains,
|
|
49
|
-
type ZoneShape,
|
|
50
|
-
} from "./zone";
|
|
38
|
+
} from "./access";
|
|
39
|
+
export {
|
|
40
|
+
BLIP_STYLE_FIELDS,
|
|
41
|
+
readBlipStyle,
|
|
42
|
+
type BlipStyle,
|
|
43
|
+
} from "./blipStyle";
|
|
44
|
+
export {
|
|
45
|
+
polyFromCorners,
|
|
46
|
+
readZoneShape,
|
|
47
|
+
zoneBounds,
|
|
48
|
+
zoneContains,
|
|
49
|
+
type ZoneShape,
|
|
50
|
+
} from "./zone";
|
|
51
51
|
export {
|
|
52
52
|
LiveRecords,
|
|
53
53
|
readRecords,
|
|
54
54
|
RecordObjects,
|
|
55
55
|
type RecordReader,
|
|
56
56
|
type RecordSource,
|
|
57
|
-
} from "./records";
|
|
58
|
-
export { formatText, LangTexts } from "./lang";
|
|
59
|
-
export { spec } from "./spec";
|
|
60
|
-
export {
|
|
61
|
-
toVehicleProps,
|
|
62
|
-
toVehicleSetup,
|
|
63
|
-
type VehicleProps,
|
|
64
|
-
type VehicleSetup,
|
|
65
|
-
} from "./vehicleProps";
|
|
66
|
-
|
|
67
|
-
export function isRecord(value: unknown): value is Record<string, unknown> {
|
|
68
|
-
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
69
|
-
}
|
|
70
|
-
|
|
71
|
-
/** Client text made safe for the server console: one line, no control characters, no `^n` colour codes. */
|
|
72
|
-
export function logSafe(text: string, max: number): string {
|
|
73
|
-
// oxlint-disable-next-line no-control-regex
|
|
74
|
-
return text
|
|
75
|
-
.replace(/\r?\n/g, " | ")
|
|
76
|
-
.replace(/[\u0000-\u001f\u007f]/g, "")
|
|
77
|
-
.replace(/\^\d/g, "")
|
|
78
|
-
.slice(0, max);
|
|
79
|
-
}
|
|
80
|
-
|
|
81
|
-
/**
|
|
82
|
-
* JSON-like text of an untrusted value cut at `max` characters, built without serializing the rest (a hostile
|
|
83
|
-
* payload can be megabytes): for log lines. Deeper than 4 levels shows as `[...]` / `{...}`.
|
|
84
|
-
*/
|
|
85
|
-
export function previewJson(value: unknown, max: number): string {
|
|
86
|
-
let out = "";
|
|
87
|
-
const walk = (v: unknown, depth: number): void => {
|
|
88
|
-
if (out.length >= max) return;
|
|
89
|
-
if (typeof v === "string") {
|
|
90
|
-
out += JSON.stringify(v.length > max ? v.slice(0, max) : v);
|
|
91
|
-
return;
|
|
92
|
-
}
|
|
93
|
-
if (v === null || typeof v !== "object") {
|
|
94
|
-
out += String(v);
|
|
95
|
-
return;
|
|
96
|
-
}
|
|
97
|
-
if (depth > 4) {
|
|
98
|
-
out += Array.isArray(v) ? "[...]" : "{...}";
|
|
99
|
-
return;
|
|
100
|
-
}
|
|
101
|
-
if (Array.isArray(v)) {
|
|
102
|
-
out += "[";
|
|
103
|
-
for (let i = 0; i < v.length && out.length < max; i++) {
|
|
104
|
-
if (i > 0) out += ",";
|
|
105
|
-
walk(v[i], depth + 1);
|
|
106
|
-
}
|
|
107
|
-
out += "]";
|
|
108
|
-
return;
|
|
109
|
-
}
|
|
110
|
-
out += "{";
|
|
111
|
-
let first = true;
|
|
112
|
-
for (const key in v) {
|
|
113
|
-
if (out.length >= max) break;
|
|
114
|
-
if (!first) out += ",";
|
|
115
|
-
first = false;
|
|
116
|
-
out += `${JSON.stringify(key.slice(0, 50))}:`;
|
|
117
|
-
walk((v as Record<string, unknown>)[key], depth + 1);
|
|
118
|
-
}
|
|
119
|
-
out += "}";
|
|
120
|
-
};
|
|
121
|
-
walk(value, 0);
|
|
122
|
-
return out.slice(0, max);
|
|
123
|
-
}
|
|
124
|
-
|
|
125
|
-
/** GTA vehicle class (`GetVehicleClassFromName`) -> the type `CreateVehicleServerSetter` wants. */
|
|
126
|
-
export function vehicleTypeOfClass(vehicleClass: number): string {
|
|
127
|
-
switch (vehicleClass) {
|
|
128
|
-
case 8:
|
|
129
|
-
case 13:
|
|
130
|
-
return "bike";
|
|
131
|
-
case 14:
|
|
132
|
-
return "boat";
|
|
133
|
-
case 15:
|
|
134
|
-
return "heli";
|
|
135
|
-
case 16:
|
|
136
|
-
return "plane";
|
|
137
|
-
case 21:
|
|
138
|
-
return "train";
|
|
139
|
-
default:
|
|
140
|
-
return "automobile";
|
|
141
|
-
}
|
|
142
|
-
}
|
|
143
|
-
|
|
144
|
-
/** One parsed value as an `args` result: `[value]`, or null to refuse the call. */
|
|
145
|
-
export const asArgs = <T>(value: T | null): [T] | null =>
|
|
146
|
-
value === null ? null : [value];
|
|
147
|
-
|
|
148
|
-
export interface Logger {
|
|
149
|
-
info(message: string, ...details: unknown[]): void;
|
|
150
|
-
warn(message: string, ...details: unknown[]): void;
|
|
151
|
-
error(message: string, ...details: unknown[]): void;
|
|
152
|
-
}
|
|
153
|
-
|
|
154
|
-
/** Console output prefixed with the resource name, so server logs show where a line came from. */
|
|
155
|
-
export function createLogger(resource: string): Logger {
|
|
156
|
-
const prefix = `[${resource}]`;
|
|
157
|
-
return {
|
|
158
|
-
info: (message, ...details) =>
|
|
159
|
-
console.log(`${prefix} ${message}`, ...details),
|
|
160
|
-
warn: (message, ...details) =>
|
|
161
|
-
console.warn(`${prefix} ^3${message}^7`, ...details),
|
|
162
|
-
error: (message, ...details) =>
|
|
163
|
-
console.error(`${prefix} ^1${message}^7`, ...details),
|
|
164
|
-
};
|
|
165
|
-
}
|
|
166
|
-
|
|
167
|
-
/** A data file's `"$schema"` key is for editors only: readers of panel files never see it. */
|
|
168
|
-
export function withoutSchemaKey(value: unknown): unknown {
|
|
169
|
-
if (!isRecord(value) || !("$schema" in value)) return value;
|
|
170
|
-
const { $schema: _schema, ...rest } = value;
|
|
171
|
-
return rest;
|
|
172
|
-
}
|
|
173
|
-
export {
|
|
174
|
-
PLACE_PED_SPEC,
|
|
175
|
-
placePedFields,
|
|
176
|
-
readPlacePed,
|
|
177
|
-
type PlacePed,
|
|
178
|
-
} from "./placePed";
|
|
179
|
-
export { cellKey, gridCell } from "./grid";
|
|
57
|
+
} from "./records";
|
|
58
|
+
export { formatText, LangTexts } from "./lang";
|
|
59
|
+
export { spec } from "./spec";
|
|
60
|
+
export {
|
|
61
|
+
toVehicleProps,
|
|
62
|
+
toVehicleSetup,
|
|
63
|
+
type VehicleProps,
|
|
64
|
+
type VehicleSetup,
|
|
65
|
+
} from "./vehicleProps";
|
|
66
|
+
|
|
67
|
+
export function isRecord(value: unknown): value is Record<string, unknown> {
|
|
68
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** Client text made safe for the server console: one line, no control characters, no `^n` colour codes. */
|
|
72
|
+
export function logSafe(text: string, max: number): string {
|
|
73
|
+
// oxlint-disable-next-line no-control-regex
|
|
74
|
+
return text
|
|
75
|
+
.replace(/\r?\n/g, " | ")
|
|
76
|
+
.replace(/[\u0000-\u001f\u007f]/g, "")
|
|
77
|
+
.replace(/\^\d/g, "")
|
|
78
|
+
.slice(0, max);
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* JSON-like text of an untrusted value cut at `max` characters, built without serializing the rest (a hostile
|
|
83
|
+
* payload can be megabytes): for log lines. Deeper than 4 levels shows as `[...]` / `{...}`.
|
|
84
|
+
*/
|
|
85
|
+
export function previewJson(value: unknown, max: number): string {
|
|
86
|
+
let out = "";
|
|
87
|
+
const walk = (v: unknown, depth: number): void => {
|
|
88
|
+
if (out.length >= max) return;
|
|
89
|
+
if (typeof v === "string") {
|
|
90
|
+
out += JSON.stringify(v.length > max ? v.slice(0, max) : v);
|
|
91
|
+
return;
|
|
92
|
+
}
|
|
93
|
+
if (v === null || typeof v !== "object") {
|
|
94
|
+
out += String(v);
|
|
95
|
+
return;
|
|
96
|
+
}
|
|
97
|
+
if (depth > 4) {
|
|
98
|
+
out += Array.isArray(v) ? "[...]" : "{...}";
|
|
99
|
+
return;
|
|
100
|
+
}
|
|
101
|
+
if (Array.isArray(v)) {
|
|
102
|
+
out += "[";
|
|
103
|
+
for (let i = 0; i < v.length && out.length < max; i++) {
|
|
104
|
+
if (i > 0) out += ",";
|
|
105
|
+
walk(v[i], depth + 1);
|
|
106
|
+
}
|
|
107
|
+
out += "]";
|
|
108
|
+
return;
|
|
109
|
+
}
|
|
110
|
+
out += "{";
|
|
111
|
+
let first = true;
|
|
112
|
+
for (const key in v) {
|
|
113
|
+
if (out.length >= max) break;
|
|
114
|
+
if (!first) out += ",";
|
|
115
|
+
first = false;
|
|
116
|
+
out += `${JSON.stringify(key.slice(0, 50))}:`;
|
|
117
|
+
walk((v as Record<string, unknown>)[key], depth + 1);
|
|
118
|
+
}
|
|
119
|
+
out += "}";
|
|
120
|
+
};
|
|
121
|
+
walk(value, 0);
|
|
122
|
+
return out.slice(0, max);
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/** GTA vehicle class (`GetVehicleClassFromName`) -> the type `CreateVehicleServerSetter` wants. */
|
|
126
|
+
export function vehicleTypeOfClass(vehicleClass: number): string {
|
|
127
|
+
switch (vehicleClass) {
|
|
128
|
+
case 8:
|
|
129
|
+
case 13:
|
|
130
|
+
return "bike";
|
|
131
|
+
case 14:
|
|
132
|
+
return "boat";
|
|
133
|
+
case 15:
|
|
134
|
+
return "heli";
|
|
135
|
+
case 16:
|
|
136
|
+
return "plane";
|
|
137
|
+
case 21:
|
|
138
|
+
return "train";
|
|
139
|
+
default:
|
|
140
|
+
return "automobile";
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/** One parsed value as an `args` result: `[value]`, or null to refuse the call. */
|
|
145
|
+
export const asArgs = <T>(value: T | null): [T] | null =>
|
|
146
|
+
value === null ? null : [value];
|
|
147
|
+
|
|
148
|
+
export interface Logger {
|
|
149
|
+
info(message: string, ...details: unknown[]): void;
|
|
150
|
+
warn(message: string, ...details: unknown[]): void;
|
|
151
|
+
error(message: string, ...details: unknown[]): void;
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
/** Console output prefixed with the resource name, so server logs show where a line came from. */
|
|
155
|
+
export function createLogger(resource: string): Logger {
|
|
156
|
+
const prefix = `[${resource}]`;
|
|
157
|
+
return {
|
|
158
|
+
info: (message, ...details) =>
|
|
159
|
+
console.log(`${prefix} ${message}`, ...details),
|
|
160
|
+
warn: (message, ...details) =>
|
|
161
|
+
console.warn(`${prefix} ^3${message}^7`, ...details),
|
|
162
|
+
error: (message, ...details) =>
|
|
163
|
+
console.error(`${prefix} ^1${message}^7`, ...details),
|
|
164
|
+
};
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/** A data file's `"$schema"` key is for editors only: readers of panel files never see it. */
|
|
168
|
+
export function withoutSchemaKey(value: unknown): unknown {
|
|
169
|
+
if (!isRecord(value) || !("$schema" in value)) return value;
|
|
170
|
+
const { $schema: _schema, ...rest } = value;
|
|
171
|
+
return rest;
|
|
172
|
+
}
|
|
173
|
+
export {
|
|
174
|
+
PLACE_PED_SPEC,
|
|
175
|
+
placePedFields,
|
|
176
|
+
readPlacePed,
|
|
177
|
+
type PlacePed,
|
|
178
|
+
} from "./placePed";
|
|
179
|
+
export { cellKey, gridCell } from "./grid";
|
package/src/shared/lang.ts
CHANGED
|
@@ -1,39 +1,39 @@
|
|
|
1
|
-
/** Fills `{0}`, `{1}`... with the arguments by position (a translation may reorder or repeat them). */
|
|
2
|
-
export function formatText(
|
|
3
|
-
template: string,
|
|
4
|
-
args: ReadonlyArray<string | number>,
|
|
5
|
-
): string {
|
|
6
|
-
return template.replace(/\{(\d+)\}/g, (match, index: string) => {
|
|
7
|
-
const value = args[Number(index)];
|
|
8
|
-
return value === undefined ? match : String(value);
|
|
9
|
-
});
|
|
10
|
-
}
|
|
11
|
-
|
|
12
|
-
/**
|
|
13
|
-
* A NUI page's lang texts (its client sends them with the screen): `translate` fills `{0}` placeholders and answers
|
|
14
|
-
* the key itself when a text is missing; `subscribe` / `snapshot` fit React's `useSyncExternalStore`. Methods are
|
|
15
|
-
* bound, so they can be passed around as plain functions.
|
|
16
|
-
*/
|
|
17
|
-
export class LangTexts {
|
|
18
|
-
private texts: Record<string, string> = {};
|
|
19
|
-
private readonly listeners = new Set<() => void>();
|
|
20
|
-
|
|
21
|
-
/** Replaces every text and tells the subscribers. */
|
|
22
|
-
readonly set = (next: Record<string, string>): void => {
|
|
23
|
-
this.texts = next;
|
|
24
|
-
for (const listener of this.listeners) listener();
|
|
25
|
-
};
|
|
26
|
-
|
|
27
|
-
/** The text of `key` with `{0}`, `{1}`... filled in; the key itself when it is missing. */
|
|
28
|
-
readonly translate = (key: string, ...args: Array<string | number>): string =>
|
|
29
|
-
formatText(this.texts[key] ?? key, args);
|
|
30
|
-
|
|
31
|
-
/** Calls `listener` after each `set`; answers the unsubscribe function. */
|
|
32
|
-
readonly subscribe = (listener: () => void): (() => void) => {
|
|
33
|
-
this.listeners.add(listener);
|
|
34
|
-
return () => this.listeners.delete(listener);
|
|
35
|
-
};
|
|
36
|
-
|
|
37
|
-
/** The current texts (a new object after each `set`). */
|
|
38
|
-
readonly snapshot = (): Record<string, string> => this.texts;
|
|
39
|
-
}
|
|
1
|
+
/** Fills `{0}`, `{1}`... with the arguments by position (a translation may reorder or repeat them). */
|
|
2
|
+
export function formatText(
|
|
3
|
+
template: string,
|
|
4
|
+
args: ReadonlyArray<string | number>,
|
|
5
|
+
): string {
|
|
6
|
+
return template.replace(/\{(\d+)\}/g, (match, index: string) => {
|
|
7
|
+
const value = args[Number(index)];
|
|
8
|
+
return value === undefined ? match : String(value);
|
|
9
|
+
});
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* A NUI page's lang texts (its client sends them with the screen): `translate` fills `{0}` placeholders and answers
|
|
14
|
+
* the key itself when a text is missing; `subscribe` / `snapshot` fit React's `useSyncExternalStore`. Methods are
|
|
15
|
+
* bound, so they can be passed around as plain functions.
|
|
16
|
+
*/
|
|
17
|
+
export class LangTexts {
|
|
18
|
+
private texts: Record<string, string> = {};
|
|
19
|
+
private readonly listeners = new Set<() => void>();
|
|
20
|
+
|
|
21
|
+
/** Replaces every text and tells the subscribers. */
|
|
22
|
+
readonly set = (next: Record<string, string>): void => {
|
|
23
|
+
this.texts = next;
|
|
24
|
+
for (const listener of this.listeners) listener();
|
|
25
|
+
};
|
|
26
|
+
|
|
27
|
+
/** The text of `key` with `{0}`, `{1}`... filled in; the key itself when it is missing. */
|
|
28
|
+
readonly translate = (key: string, ...args: Array<string | number>): string =>
|
|
29
|
+
formatText(this.texts[key] ?? key, args);
|
|
30
|
+
|
|
31
|
+
/** Calls `listener` after each `set`; answers the unsubscribe function. */
|
|
32
|
+
readonly subscribe = (listener: () => void): (() => void) => {
|
|
33
|
+
this.listeners.add(listener);
|
|
34
|
+
return () => this.listeners.delete(listener);
|
|
35
|
+
};
|
|
36
|
+
|
|
37
|
+
/** The current texts (a new object after each `set`). */
|
|
38
|
+
readonly snapshot = (): Record<string, string> => this.texts;
|
|
39
|
+
}
|
package/src/shared/read.ts
CHANGED
|
@@ -1,60 +1,60 @@
|
|
|
1
|
-
/** Small readers for panel content (`data/*.json`): every one returns the fallback when the value is missing or wrong. */
|
|
2
|
-
|
|
3
|
-
/** A finite number clamped to `[min, max]`, else the fallback. */
|
|
4
|
-
export function num(
|
|
5
|
-
value: unknown,
|
|
6
|
-
fallback: number,
|
|
7
|
-
min = -Infinity,
|
|
8
|
-
max = Infinity,
|
|
9
|
-
): number {
|
|
10
|
-
return typeof value === "number" && Number.isFinite(value)
|
|
11
|
-
? Math.min(max, Math.max(min, value))
|
|
12
|
-
: fallback;
|
|
13
|
-
}
|
|
14
|
-
|
|
15
|
-
/** `num` rounded to an integer. */
|
|
16
|
-
export function int(
|
|
17
|
-
value: unknown,
|
|
18
|
-
fallback: number,
|
|
19
|
-
min = -Infinity,
|
|
20
|
-
max = Infinity,
|
|
21
|
-
): number {
|
|
22
|
-
return Math.round(num(value, fallback, min, max));
|
|
23
|
-
}
|
|
24
|
-
|
|
25
|
-
/** A boolean, else the fallback. */
|
|
26
|
-
export function bool(value: unknown, fallback: boolean): boolean {
|
|
27
|
-
return typeof value === "boolean" ? value : fallback;
|
|
28
|
-
}
|
|
29
|
-
|
|
30
|
-
/** A trimmed non-empty string cut to `max`, else the fallback. */
|
|
31
|
-
export function str(value: unknown, fallback: string, max = 64): string {
|
|
32
|
-
return typeof value === "string" && value.trim()
|
|
33
|
-
? value.trim().slice(0, max)
|
|
34
|
-
: fallback;
|
|
35
|
-
}
|
|
36
|
-
|
|
37
|
-
/** The value as a plain object, or an empty one. */
|
|
38
|
-
export function record(value: unknown): Record<string, unknown> {
|
|
39
|
-
return typeof value === "object" && value !== null && !Array.isArray(value)
|
|
40
|
-
? (value as Record<string, unknown>)
|
|
41
|
-
: {};
|
|
42
|
-
}
|
|
43
|
-
|
|
44
|
-
export interface Vec4 {
|
|
45
|
-
x: number;
|
|
46
|
-
y: number;
|
|
47
|
-
z: number;
|
|
48
|
-
heading: number;
|
|
49
|
-
}
|
|
50
|
-
|
|
51
|
-
/** A position with heading; each missing field comes from the fallback. */
|
|
52
|
-
export function vec4(value: unknown, fallback: Vec4): Vec4 {
|
|
53
|
-
const v = record(value);
|
|
54
|
-
return {
|
|
55
|
-
x: num(v.x, fallback.x),
|
|
56
|
-
y: num(v.y, fallback.y),
|
|
57
|
-
z: num(v.z, fallback.z),
|
|
58
|
-
heading: num(v.heading, fallback.heading),
|
|
59
|
-
};
|
|
60
|
-
}
|
|
1
|
+
/** Small readers for panel content (`data/*.json`): every one returns the fallback when the value is missing or wrong. */
|
|
2
|
+
|
|
3
|
+
/** A finite number clamped to `[min, max]`, else the fallback. */
|
|
4
|
+
export function num(
|
|
5
|
+
value: unknown,
|
|
6
|
+
fallback: number,
|
|
7
|
+
min = -Infinity,
|
|
8
|
+
max = Infinity,
|
|
9
|
+
): number {
|
|
10
|
+
return typeof value === "number" && Number.isFinite(value)
|
|
11
|
+
? Math.min(max, Math.max(min, value))
|
|
12
|
+
: fallback;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
/** `num` rounded to an integer. */
|
|
16
|
+
export function int(
|
|
17
|
+
value: unknown,
|
|
18
|
+
fallback: number,
|
|
19
|
+
min = -Infinity,
|
|
20
|
+
max = Infinity,
|
|
21
|
+
): number {
|
|
22
|
+
return Math.round(num(value, fallback, min, max));
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/** A boolean, else the fallback. */
|
|
26
|
+
export function bool(value: unknown, fallback: boolean): boolean {
|
|
27
|
+
return typeof value === "boolean" ? value : fallback;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** A trimmed non-empty string cut to `max`, else the fallback. */
|
|
31
|
+
export function str(value: unknown, fallback: string, max = 64): string {
|
|
32
|
+
return typeof value === "string" && value.trim()
|
|
33
|
+
? value.trim().slice(0, max)
|
|
34
|
+
: fallback;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** The value as a plain object, or an empty one. */
|
|
38
|
+
export function record(value: unknown): Record<string, unknown> {
|
|
39
|
+
return typeof value === "object" && value !== null && !Array.isArray(value)
|
|
40
|
+
? (value as Record<string, unknown>)
|
|
41
|
+
: {};
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
export interface Vec4 {
|
|
45
|
+
x: number;
|
|
46
|
+
y: number;
|
|
47
|
+
z: number;
|
|
48
|
+
heading: number;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/** A position with heading; each missing field comes from the fallback. */
|
|
52
|
+
export function vec4(value: unknown, fallback: Vec4): Vec4 {
|
|
53
|
+
const v = record(value);
|
|
54
|
+
return {
|
|
55
|
+
x: num(v.x, fallback.x),
|
|
56
|
+
y: num(v.y, fallback.y),
|
|
57
|
+
z: num(v.z, fallback.z),
|
|
58
|
+
heading: num(v.heading, fallback.heading),
|
|
59
|
+
};
|
|
60
|
+
}
|
package/src/shared/strict.ts
CHANGED
|
@@ -1,70 +1,70 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Strict readers for client input (callback and event arguments): a wrong value is refused with null, never replaced
|
|
3
|
-
* by a fallback (that is what the panel readers `num` / `int` do).
|
|
4
|
-
*/
|
|
5
|
-
|
|
6
|
-
/** A finite number, else null (NaN and Infinity refused). */
|
|
7
|
-
export function readFinite(value: unknown): number | null {
|
|
8
|
-
return typeof value === "number" && Number.isFinite(value) ? value : null;
|
|
9
|
-
}
|
|
10
|
-
|
|
11
|
-
/** A whole number in `[min, max]`, else null (fractions, NaN, Infinity and out-of-range values refused). */
|
|
12
|
-
export function readInt(
|
|
13
|
-
value: unknown,
|
|
14
|
-
min: number,
|
|
15
|
-
max: number,
|
|
16
|
-
): number | null {
|
|
17
|
-
return Number.isInteger(value) &&
|
|
18
|
-
(value as number) >= min &&
|
|
19
|
-
(value as number) <= max
|
|
20
|
-
? (value as number)
|
|
21
|
-
: null;
|
|
22
|
-
}
|
|
23
|
-
|
|
24
|
-
/** A token or network id: a positive 32-bit integer, else null. */
|
|
25
|
-
export const readId = (value: unknown): number | null =>
|
|
26
|
-
readInt(value, 1, 2_147_483_647);
|
|
27
|
-
|
|
28
|
-
/** A non-empty trimmed string cut to `max`, else null. */
|
|
29
|
-
export function readText(value: unknown, max: number): string | null {
|
|
30
|
-
if (typeof value !== "string") return null;
|
|
31
|
-
const text = value.trim();
|
|
32
|
-
return text ? text.slice(0, max) : null;
|
|
33
|
-
}
|
|
34
|
-
|
|
35
|
-
/** An `args` parser for inputs that take one value: `onClientCallback(name, { args: oneArg(readId) }, (source, token) => ...)`. */
|
|
36
|
-
export const oneArg =
|
|
37
|
-
<T>(read: (value: unknown) => T | null) =>
|
|
38
|
-
([value]: unknown[]): [T] | null => {
|
|
39
|
-
const parsed = read(value);
|
|
40
|
-
return parsed === null ? null : [parsed];
|
|
41
|
-
};
|
|
42
|
-
|
|
43
|
-
/** The x, y, z (and w) of `{ x, y, z }` or a Lua vector that arrived as `[x, y, z, w?]`. */
|
|
44
|
-
function parts(value: unknown): unknown[] | null {
|
|
45
|
-
if (Array.isArray(value)) return value;
|
|
46
|
-
if (typeof value !== "object" || value === null) return null;
|
|
47
|
-
const v = value as Record<string, unknown>;
|
|
48
|
-
return [v.x, v.y, v.z, v.heading ?? v.w];
|
|
49
|
-
}
|
|
50
|
-
|
|
51
|
-
/** A point from client or export input: `{ x, y, z }` or a Lua vector `[x, y, z]`, every value finite; else null. */
|
|
52
|
-
export function readVec3(
|
|
53
|
-
value: unknown,
|
|
54
|
-
): { x: number; y: number; z: number } | null {
|
|
55
|
-
const p = parts(value);
|
|
56
|
-
if (!p) return null;
|
|
57
|
-
const [x, y, z] = [readFinite(p[0]), readFinite(p[1]), readFinite(p[2])];
|
|
58
|
-
return x !== null && y !== null && z !== null ? { x, y, z } : null;
|
|
59
|
-
}
|
|
60
|
-
|
|
61
|
-
/** A point with a heading: `{ x, y, z, heading | w }` or a Lua vector4; a missing heading reads 0; else null. */
|
|
62
|
-
export function readVec4(
|
|
63
|
-
value: unknown,
|
|
64
|
-
): { x: number; y: number; z: number; heading: number } | null {
|
|
65
|
-
const point = readVec3(value);
|
|
66
|
-
if (!point) return null;
|
|
67
|
-
const raw = parts(value)?.[3];
|
|
68
|
-
const heading = raw === undefined || raw === null ? 0 : readFinite(raw);
|
|
69
|
-
return heading === null ? null : { ...point, heading };
|
|
70
|
-
}
|
|
1
|
+
/**
|
|
2
|
+
* Strict readers for client input (callback and event arguments): a wrong value is refused with null, never replaced
|
|
3
|
+
* by a fallback (that is what the panel readers `num` / `int` do).
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
/** A finite number, else null (NaN and Infinity refused). */
|
|
7
|
+
export function readFinite(value: unknown): number | null {
|
|
8
|
+
return typeof value === "number" && Number.isFinite(value) ? value : null;
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
/** A whole number in `[min, max]`, else null (fractions, NaN, Infinity and out-of-range values refused). */
|
|
12
|
+
export function readInt(
|
|
13
|
+
value: unknown,
|
|
14
|
+
min: number,
|
|
15
|
+
max: number,
|
|
16
|
+
): number | null {
|
|
17
|
+
return Number.isInteger(value) &&
|
|
18
|
+
(value as number) >= min &&
|
|
19
|
+
(value as number) <= max
|
|
20
|
+
? (value as number)
|
|
21
|
+
: null;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/** A token or network id: a positive 32-bit integer, else null. */
|
|
25
|
+
export const readId = (value: unknown): number | null =>
|
|
26
|
+
readInt(value, 1, 2_147_483_647);
|
|
27
|
+
|
|
28
|
+
/** A non-empty trimmed string cut to `max`, else null. */
|
|
29
|
+
export function readText(value: unknown, max: number): string | null {
|
|
30
|
+
if (typeof value !== "string") return null;
|
|
31
|
+
const text = value.trim();
|
|
32
|
+
return text ? text.slice(0, max) : null;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** An `args` parser for inputs that take one value: `onClientCallback(name, { args: oneArg(readId) }, (source, token) => ...)`. */
|
|
36
|
+
export const oneArg =
|
|
37
|
+
<T>(read: (value: unknown) => T | null) =>
|
|
38
|
+
([value]: unknown[]): [T] | null => {
|
|
39
|
+
const parsed = read(value);
|
|
40
|
+
return parsed === null ? null : [parsed];
|
|
41
|
+
};
|
|
42
|
+
|
|
43
|
+
/** The x, y, z (and w) of `{ x, y, z }` or a Lua vector that arrived as `[x, y, z, w?]`. */
|
|
44
|
+
function parts(value: unknown): unknown[] | null {
|
|
45
|
+
if (Array.isArray(value)) return value;
|
|
46
|
+
if (typeof value !== "object" || value === null) return null;
|
|
47
|
+
const v = value as Record<string, unknown>;
|
|
48
|
+
return [v.x, v.y, v.z, v.heading ?? v.w];
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/** A point from client or export input: `{ x, y, z }` or a Lua vector `[x, y, z]`, every value finite; else null. */
|
|
52
|
+
export function readVec3(
|
|
53
|
+
value: unknown,
|
|
54
|
+
): { x: number; y: number; z: number } | null {
|
|
55
|
+
const p = parts(value);
|
|
56
|
+
if (!p) return null;
|
|
57
|
+
const [x, y, z] = [readFinite(p[0]), readFinite(p[1]), readFinite(p[2])];
|
|
58
|
+
return x !== null && y !== null && z !== null ? { x, y, z } : null;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** A point with a heading: `{ x, y, z, heading | w }` or a Lua vector4; a missing heading reads 0; else null. */
|
|
62
|
+
export function readVec4(
|
|
63
|
+
value: unknown,
|
|
64
|
+
): { x: number; y: number; z: number; heading: number } | null {
|
|
65
|
+
const point = readVec3(value);
|
|
66
|
+
if (!point) return null;
|
|
67
|
+
const raw = parts(value)?.[3];
|
|
68
|
+
const heading = raw === undefined || raw === null ? 0 : readFinite(raw);
|
|
69
|
+
return heading === null ? null : { ...point, heading };
|
|
70
|
+
}
|