@rbxts/scribe 2.6.0 → 2.7.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/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, { readonly Toggle: (this: void, replicate?: boolean) => boolean }>
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
- readonly Child: <K extends Extract<keyof S, string | number>>(this: void, key: K) => Accessor<S[K], false, ChildMissing<T, Missing>, IsReadOnly<T, ReadOnly>, Closed>;
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
- type TimedMethods<T, ReadOnly extends boolean> = HasKind<T, "Timed"> extends true ? {
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
- /** Accessors are proxy objects, never native Array/Map instances. */
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