@rbxts/scribe 2.6.0 → 2.6.1
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/README.md +1 -1
- package/Scribe-source-map.json +1 -1
- package/package.json +1 -1
- package/src/Internal/Datatypes.luau +12 -6
- package/src/Internal/Signal.luau +21 -0
- package/src/Internal/Template.luau +18 -0
- package/src/Internal/Version.luau +1 -1
- package/src/Server/Replication.luau +2 -2
- package/src/Types.luau +28 -1
- package/src/init.luau +492 -118
- package/types/api.d.ts +84 -3
- package/types/common.d.ts +22 -2
- package/types/index.d.ts +58 -3
- package/types/schema.d.ts +87 -23
package/types/schema.d.ts
CHANGED
|
@@ -22,18 +22,31 @@ export type BigOperand = BigValue | number | string;
|
|
|
22
22
|
|
|
23
23
|
/** Immutable mantissa/exponent value. These are genuine Luau self methods. */
|
|
24
24
|
export interface BigValue {
|
|
25
|
+
/** The normalized mantissa, including its sign. */
|
|
25
26
|
readonly M: number;
|
|
27
|
+
/** The base-10 exponent. */
|
|
26
28
|
readonly E: number;
|
|
29
|
+
/** Returns the sum as a new Big value. */
|
|
27
30
|
Add(other: BigOperand): BigValue;
|
|
31
|
+
/** Returns the difference as a new Big value. */
|
|
28
32
|
Subtract(other: BigOperand): BigValue;
|
|
33
|
+
/** Returns the product as a new Big value. */
|
|
29
34
|
Multiply(other: BigOperand): BigValue;
|
|
35
|
+
/** Returns the quotient as a new Big value; rejects division by zero. */
|
|
30
36
|
Divide(other: BigOperand): BigValue;
|
|
37
|
+
/** Returns a new Big value with the opposite sign. */
|
|
31
38
|
Negate(): BigValue;
|
|
39
|
+
/** Returns -1, 0 or 1 when smaller, equal or larger than the other value. */
|
|
32
40
|
Compare(other: BigOperand): number;
|
|
41
|
+
/** Checks whether the numeric values are equal. */
|
|
33
42
|
Equals(other: BigOperand): boolean;
|
|
43
|
+
/** Returns a new power; the exponent must be an integer from 0 to 2^53. */
|
|
34
44
|
Pow(exponent: number): BigValue;
|
|
45
|
+
/** Returns the base-10 logarithm as a plain number. */
|
|
35
46
|
Log10(): number;
|
|
47
|
+
/** Formats a compact label, using two decimal places by default. */
|
|
36
48
|
Short(decimals?: number): string;
|
|
49
|
+
/** Converts to a plain number, which can lose precision or overflow. */
|
|
37
50
|
ToNumber(): number;
|
|
38
51
|
}
|
|
39
52
|
|
|
@@ -128,8 +141,11 @@ export type SharedSchema<T> = { [K in keyof T as IsShared<T[K]> extends true ? K
|
|
|
128
141
|
|
|
129
142
|
/** Adapters can depend on this small structural interface without knowing a schema. */
|
|
130
143
|
export interface ReadableNode<T> {
|
|
144
|
+
/** Returns the current value. */
|
|
131
145
|
readonly Get: (this: void) => T;
|
|
146
|
+
/** Calls back now and on changes; returns a disconnect function. */
|
|
132
147
|
readonly Observe: (this: void, callback: (this: void, value: T) => void) => Disconnect;
|
|
148
|
+
/** Calls back on changes with new and old values; returns a disconnect function. */
|
|
133
149
|
readonly Changed: (this: void, callback: (this: void, value: T, previous: T) => void) => Disconnect;
|
|
134
150
|
}
|
|
135
151
|
type Maybe<T, Missing extends boolean> = Missing extends true ? T | undefined : T;
|
|
@@ -137,13 +153,19 @@ type Read<T, Missing extends boolean> = Maybe<DeepReadonly<ValueOf<T>>, Missing>
|
|
|
137
153
|
interface ReadOperations<T, Missing extends boolean, Closed extends boolean> extends ReadableNode<Read<T, Missing>> {
|
|
138
154
|
/** Calling an accessor without arguments is its Get shorthand. */
|
|
139
155
|
(this: void): Read<T, Missing>;
|
|
156
|
+
/** Returns a detached, mutable copy of the current value. */
|
|
140
157
|
readonly Clone: (this: void) => Maybe<ValueOf<T>, Missing>;
|
|
158
|
+
/** Returns a copy of the declared default, or undefined for an undeclared field. */
|
|
141
159
|
readonly Default: (this: void) => Missing extends true ? Closed extends true ? ValueOf<T> : ValueOf<T> | undefined : ValueOf<T>;
|
|
142
160
|
}
|
|
143
161
|
interface WriteOperations<T, Missing extends boolean, Closed extends boolean> {
|
|
162
|
+
/** Sets the value; shorthand for Set. */
|
|
144
163
|
(this: void, value: WriteInput<T, Closed>, replicate?: boolean): ValueOf<T>;
|
|
164
|
+
/** Updates the value through a callback; shorthand for Update. */
|
|
145
165
|
(this: void, update: (this: void, current: Read<T, Missing>) => WriteInput<T, Closed>, replicate?: boolean): ValueOf<T>;
|
|
166
|
+
/** Validates and sets the value, returning the result. */
|
|
146
167
|
readonly Set: (this: void, value: WriteInput<T, Closed>, replicate?: boolean) => ValueOf<T>;
|
|
168
|
+
/** Passes the current value to the callback and validates its replacement. */
|
|
147
169
|
readonly Update: (this: void, update: (this: void, current: Read<T, Missing>) => WriteInput<T, Closed>, replicate?: boolean) => ValueOf<T>;
|
|
148
170
|
}
|
|
149
171
|
type Unwrap<T> = T extends Declaration<"ServerOnly" | "Shared" | "Session" | "Timed" | "Derived" | "Optional", infer V> ? Unwrap<V> : Exclude<T, undefined>;
|
|
@@ -156,72 +178,110 @@ type Mutate<T, Root extends boolean, Missing extends boolean, ReadOnly extends b
|
|
|
156
178
|
type Bound = number | string;
|
|
157
179
|
type AmountOptions = boolean | import("./common").EconomyMeta;
|
|
158
180
|
interface NumberRead {
|
|
181
|
+
/** Returns the declared minimum, or undefined when unbounded. */
|
|
159
182
|
readonly Min: (this: void) => number | undefined;
|
|
183
|
+
/** Returns the declared maximum, or undefined when unbounded. */
|
|
160
184
|
readonly Max: (this: void) => number | undefined;
|
|
161
185
|
}
|
|
162
186
|
interface NumberWrite {
|
|
187
|
+
/** Adds an amount and returns the updated value. */
|
|
163
188
|
readonly Increment: (this: void, amount: number, options?: AmountOptions) => number;
|
|
189
|
+
/** Subtracts an amount and returns the updated value. */
|
|
164
190
|
readonly Decrement: (this: void, amount: number, options?: AmountOptions) => number;
|
|
165
191
|
}
|
|
166
192
|
interface BigRead {
|
|
193
|
+
/** Returns the declared minimum, or undefined when unbounded. */
|
|
167
194
|
readonly Min: (this: void) => Bound | undefined;
|
|
195
|
+
/** Returns the declared maximum, or undefined when unbounded. */
|
|
168
196
|
readonly Max: (this: void) => Bound | undefined;
|
|
169
197
|
}
|
|
170
198
|
interface BigWrite {
|
|
199
|
+
/** Adds an amount and returns the updated Big value. */
|
|
171
200
|
readonly Increment: (this: void, amount: BigOperand, options?: AmountOptions) => BigValue;
|
|
201
|
+
/** Subtracts an amount and returns the updated Big value. */
|
|
172
202
|
readonly Decrement: (this: void, amount: BigOperand, options?: AmountOptions) => BigValue;
|
|
203
|
+
/** Multiplies the field and returns the updated Big value. */
|
|
173
204
|
readonly Multiply: (this: void, amount: BigOperand, replicate?: boolean) => BigValue;
|
|
205
|
+
/** Divides the field and returns the updated Big value; rejects zero. */
|
|
174
206
|
readonly Divide: (this: void, amount: BigOperand, replicate?: boolean) => BigValue;
|
|
175
207
|
}
|
|
176
208
|
type WritableOnly<T, ReadOnly extends boolean, Methods> = IsReadOnly<T, ReadOnly> extends true ? {} : Methods;
|
|
177
209
|
type ScalarMethods<T, ReadOnly extends boolean> = Unwrap<T> extends number ? NumberRead & WritableOnly<T, ReadOnly, NumberWrite>
|
|
178
|
-
: Unwrap<T> extends boolean ? WritableOnly<T, ReadOnly, {
|
|
210
|
+
: Unwrap<T> extends boolean ? WritableOnly<T, ReadOnly, {
|
|
211
|
+
/** Flips the boolean and returns its new value. */
|
|
212
|
+
readonly Toggle: (this: void, replicate?: boolean) => boolean
|
|
213
|
+
}>
|
|
179
214
|
: Unwrap<T> extends BigSchema | BigValue ? BigRead & WritableOnly<T, ReadOnly, BigWrite> : {};
|
|
180
215
|
|
|
181
216
|
type ChildEvents<K, V> = {
|
|
217
|
+
/** Observes child changes by key; returns a disconnect function. */
|
|
182
218
|
readonly OnChildChanged: (this: void, callback: (this: void, key: K, value: DeepReadonly<V> | undefined, previous: DeepReadonly<V> | undefined) => void) => Disconnect;
|
|
183
219
|
};
|
|
184
|
-
type CollectionRead<K, E, ReadOnly extends boolean, Closed extends boolean> = ChildEvents<K, ValueOf<E>> & {
|
|
220
|
+
type CollectionRead<K, E, ReadOnly extends boolean, Closed extends boolean, Client extends boolean> = ChildEvents<K, ValueOf<E>> & {
|
|
185
221
|
/** Exact Luau key. Array positions start at 1; map keys are never shifted. */
|
|
186
|
-
readonly Child: (this: void, key: K) => Accessor<E, false, true, ReadOnly, Closed>;
|
|
222
|
+
readonly Child: (this: void, key: K) => Accessor<E, false, true, ReadOnly, Closed, Client>;
|
|
223
|
+
/** Returns the number of entries. */
|
|
187
224
|
readonly Count: (this: void) => number;
|
|
188
225
|
};
|
|
189
|
-
type ArrayMethods<T, E, ReadOnly extends boolean, Closed extends boolean> = CollectionRead<number, E, ReadOnly, Closed> & {
|
|
190
|
-
readonly [index: number]: Accessor<E, false, true, ReadOnly, Closed>;
|
|
226
|
+
type ArrayMethods<T, E, ReadOnly extends boolean, Closed extends boolean, Client extends boolean> = CollectionRead<number, E, ReadOnly, Closed, Client> & {
|
|
227
|
+
readonly [index: number]: Accessor<E, false, true, ReadOnly, Closed, Client>;
|
|
228
|
+
/** Returns the first 1-based position, or undefined when absent. */
|
|
191
229
|
readonly Find: (this: void, value: InputOf<E>) => number | undefined;
|
|
230
|
+
/** Checks whether the collection contains the value. */
|
|
192
231
|
readonly Has: (this: void, value: InputOf<E>) => boolean;
|
|
232
|
+
/** Observes insertions with the value and position; returns a disconnect function. */
|
|
193
233
|
readonly OnInsert: (this: void, callback: (this: void, value: DeepReadonly<ValueOf<E>>, index: number) => void) => Disconnect;
|
|
234
|
+
/** Observes removals with the value and former position; returns a disconnect function. */
|
|
194
235
|
readonly OnRemove: (this: void, callback: (this: void, value: DeepReadonly<ValueOf<E>>, index: number) => void) => Disconnect;
|
|
195
236
|
} & WritableOnly<T, ReadOnly, {
|
|
237
|
+
/** Inserts at a 1-based position, or appends when omitted. */
|
|
196
238
|
readonly Insert: (this: void, value: WriteInput<E, Closed>, position?: number, replicate?: boolean) => void;
|
|
239
|
+
/** Removes and returns an entry, defaulting to the last position. */
|
|
197
240
|
readonly Remove: (this: void, position?: number, replicate?: boolean) => ValueOf<E> | undefined;
|
|
241
|
+
/** Removes the first match and returns its value and position, or two undefined values. */
|
|
198
242
|
readonly RemoveValue: (this: void, value: InputOf<E>, replicate?: boolean) => LuaTuple<[ValueOf<E> | undefined, number | undefined]>;
|
|
243
|
+
/** Removes every entry. */
|
|
199
244
|
readonly Clear: (this: void, replicate?: boolean) => void;
|
|
200
245
|
}>;
|
|
201
|
-
type DictMethods<T, K extends string | number, E, ReadOnly extends boolean, Closed extends boolean> = CollectionRead<K, E, ReadOnly, Closed> & {
|
|
202
|
-
readonly [P in K]: Accessor<E, false, true, ReadOnly, Closed>;
|
|
246
|
+
type DictMethods<T, K extends string | number, E, ReadOnly extends boolean, Closed extends boolean, Client extends boolean> = CollectionRead<K, E, ReadOnly, Closed, Client> & {
|
|
247
|
+
readonly [P in K]: Accessor<E, false, true, ReadOnly, Closed, Client>;
|
|
203
248
|
} & {
|
|
249
|
+
/** Observes new keys and their values; returns a disconnect function. */
|
|
204
250
|
readonly OnKeyAdded: (this: void, callback: (this: void, key: K, value: DeepReadonly<ValueOf<E>>) => void) => Disconnect;
|
|
251
|
+
/** Observes removed keys and their values; returns a disconnect function. */
|
|
205
252
|
readonly OnKeyRemoved: (this: void, callback: (this: void, key: K, value: DeepReadonly<ValueOf<E>>) => void) => Disconnect;
|
|
206
253
|
} & WritableOnly<T, ReadOnly, {
|
|
254
|
+
/** Removes the key and returns its previous value, or undefined when absent. */
|
|
207
255
|
readonly Remove: (this: void, key: K, replicate?: boolean) => ValueOf<E> | undefined;
|
|
256
|
+
/** Removes every entry. */
|
|
208
257
|
readonly Clear: (this: void, replicate?: boolean) => void;
|
|
209
258
|
}>;
|
|
210
259
|
type SetMethods<T, E, ReadOnly extends boolean> = {
|
|
260
|
+
/** Checks whether the collection contains the value. */
|
|
211
261
|
readonly Has: (this: void, value: InputOf<E>) => boolean;
|
|
262
|
+
/** Returns the first 1-based position, or undefined when absent. */
|
|
212
263
|
readonly Find: (this: void, value: InputOf<E>) => number | undefined;
|
|
264
|
+
/** Returns the number of entries. */
|
|
213
265
|
readonly Count: (this: void) => number;
|
|
214
266
|
} & WritableOnly<T, ReadOnly, {
|
|
267
|
+
/** Adds a set member; returns false if already present. */
|
|
215
268
|
readonly Add: (this: void, value: InputOf<E>, replicate?: boolean) => boolean;
|
|
269
|
+
/** Removes a set member; returns false if absent. */
|
|
216
270
|
readonly Remove: (this: void, value: InputOf<E>, replicate?: boolean) => boolean;
|
|
271
|
+
/** Removes every entry. */
|
|
217
272
|
readonly Clear: (this: void, replicate?: boolean) => void;
|
|
218
273
|
}>;
|
|
219
274
|
type FlagsMethods<T, K extends string, ReadOnly extends boolean> = {
|
|
275
|
+
/** Checks whether the flag is enabled. */
|
|
220
276
|
readonly Has: (this: void, member: K) => boolean;
|
|
221
277
|
} & WritableOnly<T, ReadOnly, {
|
|
278
|
+
/** Enables the named flag. */
|
|
222
279
|
readonly Enable: (this: void, member: K, replicate?: boolean) => void;
|
|
280
|
+
/** Disables the named flag. */
|
|
223
281
|
readonly Disable: (this: void, member: K, replicate?: boolean) => void;
|
|
282
|
+
/** Flips the named flag and returns whether it is enabled. */
|
|
224
283
|
readonly Toggle: (this: void, member: K, replicate?: boolean) => boolean;
|
|
284
|
+
/** Disables every flag. */
|
|
225
285
|
readonly Clear: (this: void, replicate?: boolean) => void;
|
|
226
286
|
}>;
|
|
227
287
|
type ReservedMethod = "Get" | "Set" | "Update" | "Clone" | "Default" | "Changed" | "Observe" | "Child" |
|
|
@@ -229,36 +289,40 @@ type ReservedMethod = "Get" | "Set" | "Update" | "Clone" | "Default" | "Changed"
|
|
|
229
289
|
"OnInsert" | "OnRemove" | "OnKeyAdded" | "OnKeyRemoved" | "Increment" | "Decrement" | "Min" | "Max" |
|
|
230
290
|
"Toggle" | "Enable" | "Disable" | "Add" | "Multiply" | "Divide" | "SetTimed" | "ExtendTimed" | "Active";
|
|
231
291
|
type ChildMissing<T, Missing extends boolean> = Missing extends true ? true : OptionalField<T>;
|
|
232
|
-
type RecordMethods<T, S, Missing extends boolean, ReadOnly extends boolean, Closed extends boolean> = {
|
|
233
|
-
readonly [K in keyof S as K extends ReservedMethod ? never : K]-?: Accessor<S[K], false, ChildMissing<T, Missing>, IsReadOnly<T, ReadOnly>, Closed>;
|
|
292
|
+
type RecordMethods<T, S, Missing extends boolean, ReadOnly extends boolean, Closed extends boolean, Client extends boolean> = {
|
|
293
|
+
readonly [K in keyof S as K extends ReservedMethod ? never : K]-?: Accessor<S[K], false, ChildMissing<T, Missing>, IsReadOnly<T, ReadOnly>, Closed, Client>;
|
|
234
294
|
} & {
|
|
235
|
-
|
|
295
|
+
/** Accesses a child by name, including keys that match methods. */
|
|
296
|
+
readonly Child: <K extends Extract<keyof S, string | number>>(this: void, key: K) => Accessor<S[K], false, ChildMissing<T, Missing>, IsReadOnly<T, ReadOnly>, Closed, Client>;
|
|
236
297
|
} & ChildEvents<Extract<keyof S, string | number>, ValueOf<S[keyof S]>>;
|
|
237
298
|
|
|
238
|
-
type ShapeMethods<T, S, Missing extends boolean, ReadOnly extends boolean, Closed extends boolean> = S extends ArrayOf<infer E>
|
|
239
|
-
? ArrayMethods<T, E, ReadOnly, true>
|
|
240
|
-
: S extends DictOf<infer E> ? DictMethods<T, string, E, ReadOnly, true>
|
|
241
|
-
: S extends MapOf<infer K, infer E> ? DictMethods<T, KeyOfMap<K>, E, ReadOnly, true>
|
|
299
|
+
type ShapeMethods<T, S, Missing extends boolean, ReadOnly extends boolean, Closed extends boolean, Client extends boolean> = S extends ArrayOf<infer E>
|
|
300
|
+
? ArrayMethods<T, E, ReadOnly, true, Client>
|
|
301
|
+
: S extends DictOf<infer E> ? DictMethods<T, string, E, ReadOnly, true, Client>
|
|
302
|
+
: S extends MapOf<infer K, infer E> ? DictMethods<T, KeyOfMap<K>, E, ReadOnly, true, Client>
|
|
242
303
|
: S extends SetOf<infer E> ? SetMethods<T, E, ReadOnly>
|
|
243
304
|
: S extends Flags<infer K> ? FlagsMethods<T, K, ReadOnly>
|
|
244
305
|
: S extends Declaration<string, unknown> | AtomicValue ? {}
|
|
245
|
-
: S extends ReadonlyArray<infer E> ? ArrayMethods<T, E, ReadOnly, false>
|
|
246
|
-
: S extends object ? string extends keyof S ? DictMethods<T, string, S[string & keyof S], ReadOnly, false>
|
|
247
|
-
: number extends keyof S ? ArrayMethods<T, S[number & keyof S], ReadOnly, false>
|
|
248
|
-
: RecordMethods<T, S, Missing, ReadOnly, Closed>
|
|
306
|
+
: S extends ReadonlyArray<infer E> ? ArrayMethods<T, E, ReadOnly, false, Client>
|
|
307
|
+
: S extends object ? string extends keyof S ? DictMethods<T, string, S[string & keyof S], ReadOnly, false, Client>
|
|
308
|
+
: number extends keyof S ? ArrayMethods<T, S[number & keyof S], ReadOnly, false, Client>
|
|
309
|
+
: RecordMethods<T, S, Missing, ReadOnly, Closed, Client>
|
|
249
310
|
: {};
|
|
250
|
-
|
|
311
|
+
// Only the server changes timer deadlines.
|
|
312
|
+
type TimedMethods<T, ReadOnly extends boolean, Client extends boolean> = HasKind<T, "Timed"> extends true ? {
|
|
251
313
|
/** Timer state and seconds left. Clients read replicated deadlines; inactive returns false, undefined. */
|
|
252
314
|
readonly Active: (this: void) => LuaTuple<[boolean, number | undefined]>;
|
|
253
|
-
} & WritableOnly<T, ReadOnly, {
|
|
315
|
+
} & WritableOnly<T, Client extends true ? true : ReadOnly, {
|
|
316
|
+
/** Sets the value until its timer expires, then restores the default; server only. */
|
|
254
317
|
readonly SetTimed: (this: void, value: InputOf<T>, seconds: number, replicate?: boolean) => void;
|
|
318
|
+
/** Adds seconds to the timer, starting from now if inactive; server only. */
|
|
255
319
|
readonly ExtendTimed: (this: void, seconds: number, replicate?: boolean) => void;
|
|
256
320
|
}> : {};
|
|
257
321
|
|
|
258
|
-
/**
|
|
259
|
-
export type Accessor<T, Root extends boolean = false, Missing extends boolean = false, ReadOnly extends boolean = false, Closed extends boolean = false> =
|
|
322
|
+
/** Proxy objects, not native Array/Map instances. Client omits SetTimed/ExtendTimed. */
|
|
323
|
+
export type Accessor<T, Root extends boolean = false, Missing extends boolean = false, ReadOnly extends boolean = false, Closed extends boolean = false, Client extends boolean = false> =
|
|
260
324
|
ReadOperations<T, Missing, Closed> & Mutate<T, Root, Missing, ReadOnly, Closed> & ScalarMethods<T, ReadOnly> &
|
|
261
|
-
ShapeMethods<T, Unwrap<T>, Missing, ReadOnly, Closed> & TimedMethods<T, ReadOnly>;
|
|
325
|
+
ShapeMethods<T, Unwrap<T>, Missing, ReadOnly, Closed, Client> & TimedMethods<T, ReadOnly, Client>;
|
|
262
326
|
export type PlayerData<T> = Accessor<T, true>;
|
|
263
327
|
export type ReadonlyAccessor<T, Root extends boolean = false> = Accessor<T, Root, false, true>;
|
|
264
328
|
|