Skip to content

Commit c5d1dd8

Browse files
johnmtlljohnmtll
authored
feat(NODE-7069): deprecate Long members inapplicable to Timestamp (#887)
1 parent 0231603 commit c5d1dd8

2 files changed

Lines changed: 248 additions & 4 deletions

File tree

‎src/timestamp.ts‎

Lines changed: 157 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,53 @@ import type { Int32 } from './int_32';
44
import { Long } from './long';
55
import { type InspectFn, defaultInspect } from './parser/utils';
66

7-
/** @public */
7+
/**
8+
* @public
9+
* @deprecated This type is no longer used internally and will be removed in a future version.
10+
*/
811
export type TimestampOverrides =
912
| '_bsontype'
1013
| 'toExtendedJSON'
1114
| 'fromExtendedJSON'
1215
| 'inspect'
1316
| typeof bsonType;
17+
18+
/**
19+
* @public
20+
*
21+
* Inherited `Long` members surfaced on `Timestamp`.
22+
* When `Long` gains a new member: add it here if it should pass through, or
23+
* add a `@deprecated declare` line on the `Timestamp` class if it should be
24+
* surfaced as deprecated. Anything left unclassified is silently dropped from
25+
* the public type — preventing accidental behavioral bleed-through.
26+
*/
27+
type TimestampKept =
28+
| 'toBigInt'
29+
| 'toString'
30+
| 'compare'
31+
| 'equals'
32+
| 'eq'
33+
| 'notEquals'
34+
| 'neq'
35+
| 'ne'
36+
| 'lessThan'
37+
| 'lt'
38+
| 'lessThanOrEqual'
39+
| 'lte'
40+
| 'le'
41+
| 'greaterThan'
42+
| 'gt'
43+
| 'greaterThanOrEqual'
44+
| 'gte'
45+
| 'ge';
46+
1447
/** @public */
1548
export type LongWithoutOverrides = new (
1649
low: unknown,
1750
high?: number | boolean,
1851
unsigned?: boolean
1952
) => {
20-
[P in Exclude<keyof Long, TimestampOverrides>]: Long[P];
53+
[P in TimestampKept]: Long[P];
2154
};
2255
/** @public */
2356
export const LongWithoutOverridesClass: LongWithoutOverrides =
@@ -45,6 +78,9 @@ export class Timestamp extends LongWithoutOverridesClass {
4578
return 'Timestamp';
4679
}
4780

81+
/**
82+
* @deprecated Use `Long.MAX_UNSIGNED_VALUE` instead.
83+
*/
4884
static readonly MAX_VALUE = Long.MAX_UNSIGNED_VALUE;
4985

5086
/**
@@ -120,12 +156,18 @@ export class Timestamp extends LongWithoutOverridesClass {
120156
};
121157
}
122158

123-
/** Returns a Timestamp represented by the given (32-bit) integer value. */
159+
/**
160+
* Returns a Timestamp represented by the given (32-bit) integer value.
161+
* @deprecated Stores `value` in the low 32 bits (increment), leaving t = 0. Use `new Timestamp({ t, i })` or `Timestamp.fromBits(lowBits, highBits)` for explicit construction.
162+
*/
124163
static fromInt(value: number): Timestamp {
125164
return new Timestamp(Long.fromInt(value, true));
126165
}
127166

128-
/** Returns a Timestamp representing the given number value, provided that it is a finite number. Otherwise, zero is returned. */
167+
/**
168+
* Returns a Timestamp representing the given number value, provided that it is a finite number. Otherwise, zero is returned.
169+
* @deprecated Splits `value` across (t, i) as a uint64; the result rarely matches user intent. Use `new Timestamp({ t, i })` or `Timestamp.fromBits(lowBits, highBits)` for explicit construction.
170+
*/
129171
static fromNumber(value: number): Timestamp {
130172
return new Timestamp(Long.fromNumber(value, true));
131173
}
@@ -173,4 +215,115 @@ export class Timestamp extends LongWithoutOverridesClass {
173215
const i = inspect(this.i, options);
174216
return `new Timestamp({ t: ${t}, i: ${i} })`;
175217
}
218+
219+
// ********************
220+
// **** DEPRECATED ****
221+
// ********************
222+
// Declare used to avoid runtime effects for field declaration.
223+
// See: https://www.typescriptlang.org/docs/handbook/2/classes.html#type-only-field-declarations
224+
225+
// Arithmetic
226+
/** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
227+
declare add: Long['add'];
228+
/** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
229+
declare subtract: Long['subtract'];
230+
/** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
231+
declare sub: Long['sub'];
232+
/** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
233+
declare multiply: Long['multiply'];
234+
/** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
235+
declare mul: Long['mul'];
236+
/** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
237+
declare divide: Long['divide'];
238+
/** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
239+
declare div: Long['div'];
240+
/** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
241+
declare modulo: Long['modulo'];
242+
/** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
243+
declare mod: Long['mod'];
244+
/** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
245+
declare rem: Long['rem'];
246+
/** @deprecated Not applicable to Timestamp as the underlying Long is always unsigned. */
247+
declare negate: Long['negate'];
248+
/** @deprecated Not applicable to Timestamp as the underlying Long is always unsigned. */
249+
declare neg: Long['neg'];
250+
251+
// Bitwise / shifts
252+
/** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
253+
declare and: Long['and'];
254+
/** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
255+
declare or: Long['or'];
256+
/** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
257+
declare xor: Long['xor'];
258+
/** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
259+
declare not: Long['not'];
260+
/** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
261+
declare shiftLeft: Long['shiftLeft'];
262+
/** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
263+
declare shl: Long['shl'];
264+
/** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
265+
declare shiftRight: Long['shiftRight'];
266+
/** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
267+
declare shr: Long['shr'];
268+
/** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
269+
declare shiftRightUnsigned: Long['shiftRightUnsigned'];
270+
/** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
271+
declare shr_u: Long['shr_u'];
272+
/** @deprecated Not applicable to Timestamp; Timestamp is not intended to be used as a Long. */
273+
declare shru: Long['shru'];
274+
275+
// Signing
276+
/** @deprecated Not applicable to Timestamp as the underlying Long is always unsigned. */
277+
declare toSigned: Long['toSigned'];
278+
/** @deprecated Not applicable to Timestamp as the underlying Long is always unsigned (this is a no-op). */
279+
declare toUnsigned: Long['toUnsigned'];
280+
/** @deprecated Not applicable to Timestamp as the underlying Long is always unsigned (is always false). */
281+
declare isNegative: Long['isNegative'];
282+
/** @deprecated Not applicable to Timestamp as the underlying Long is always unsigned (is always true). */
283+
declare isPositive: Long['isPositive'];
284+
/** @deprecated Not applicable to Timestamp as the underlying Long is always unsigned (is always true). */
285+
declare unsigned: Long['unsigned'];
286+
287+
// Conversion
288+
/** @deprecated Not applicable to Timestamp; use `.t` for seconds since the Unix epoch, or `.i` for the increment ordinal. */
289+
declare toInt: Long['toInt'];
290+
/** @deprecated Not applicable to Timestamp; use `.t` for seconds since the Unix epoch, or `.i` for the increment ordinal. */
291+
declare toNumber: Long['toNumber'];
292+
/** @deprecated Not applicable to Timestamp; use `.t` for seconds since the Unix epoch, or `.i` for the increment ordinal. */
293+
declare toBytes: Long['toBytes'];
294+
/** @deprecated Not applicable to Timestamp; use `.t` for seconds since the Unix epoch, or `.i` for the increment ordinal. */
295+
declare toBytesLE: Long['toBytesLE'];
296+
/** @deprecated Not applicable to Timestamp; use `.t` for seconds since the Unix epoch, or `.i` for the increment ordinal. */
297+
declare toBytesBE: Long['toBytesBE'];
298+
299+
// Other
300+
/** @deprecated Incompatible with Timestamp: returns a signed integer, but Timestamp is always unsigned. Use `.t` for seconds since the Unix epoch. */
301+
declare getHighBits: Long['getHighBits'];
302+
/** @deprecated Not applicable to Timestamp; use `.t` for seconds since the Unix epoch. */
303+
declare getHighBitsUnsigned: Long['getHighBitsUnsigned'];
304+
/** @deprecated Incompatible with Timestamp: returns a signed integer, but Timestamp is always unsigned. Use `.i` for the increment ordinal. */
305+
declare getLowBits: Long['getLowBits'];
306+
/** @deprecated Not applicable to Timestamp; use `.i` for the increment ordinal. */
307+
declare getLowBitsUnsigned: Long['getLowBitsUnsigned'];
308+
309+
/** @deprecated Not applicable to Timestamp; use `.i` instead. */
310+
declare low: Long['low'];
311+
/** @deprecated Not applicable to Timestamp; use `.t` instead. */
312+
declare high: Long['high'];
313+
314+
/** @deprecated Use .compare() for general comparison, or .equals(), .lessThan(), .greaterThan() for specific cases. */
315+
declare comp: Long['comp'];
316+
/** @deprecated Compare `.t` and `.i` against `0` explicitly. */
317+
declare isZero: Long['isZero'];
318+
/** @deprecated Compare `.t` and `.i` against `0` explicitly. */
319+
declare eqz: Long['eqz'];
320+
321+
/** @deprecated Not applicable to Timestamp. Use the bsonType symbol or _bsontype === 'Timestamp' to identify a Timestamp. */
322+
declare __isLong__: Long['__isLong__'];
323+
/** @deprecated Not applicable to Timestamp. */
324+
declare getNumBitsAbs: Long['getNumBitsAbs'];
325+
/** @deprecated Not applicable to Timestamp; tests parity of the increment only. */
326+
declare isEven: Long['isEven'];
327+
/** @deprecated Not applicable to Timestamp; tests parity of the increment only. */
328+
declare isOdd: Long['isOdd'];
176329
}

‎test/types/bson.test-d.ts‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,3 +119,94 @@ expectError(new ObjectId(42 as string | number));
119119
new Timestamp(new Timestamp(0n))
120120

121121
expectType<(position: number, length: number) => Uint8Array>(Binary.prototype.read);
122+
123+
// NODE-7069: TimestampKept members must be accessible and non-deprecated
124+
declare const timestamp: Timestamp;
125+
expectNotDeprecated(timestamp.toString);
126+
expectNotDeprecated(timestamp.compare);
127+
expectNotDeprecated(timestamp.equals);
128+
expectNotDeprecated(timestamp.eq);
129+
expectNotDeprecated(timestamp.notEquals);
130+
expectNotDeprecated(timestamp.neq);
131+
expectNotDeprecated(timestamp.ne);
132+
expectNotDeprecated(timestamp.lessThan);
133+
expectNotDeprecated(timestamp.lt);
134+
expectNotDeprecated(timestamp.lessThanOrEqual);
135+
expectNotDeprecated(timestamp.lte);
136+
expectNotDeprecated(timestamp.le);
137+
expectNotDeprecated(timestamp.greaterThan);
138+
expectNotDeprecated(timestamp.gt);
139+
expectNotDeprecated(timestamp.greaterThanOrEqual);
140+
expectNotDeprecated(timestamp.gte);
141+
expectNotDeprecated(timestamp.ge);
142+
expectNotDeprecated(timestamp.toBigInt);
143+
144+
// Timestamp's own instance members must not be deprecated
145+
expectNotDeprecated(timestamp.t);
146+
expectNotDeprecated(timestamp.i);
147+
expectNotDeprecated(timestamp.toJSON);
148+
149+
// Non-deprecated static methods
150+
expectNotDeprecated(Timestamp.fromBits);
151+
expectNotDeprecated(Timestamp.fromString);
152+
153+
// Deprecated static members
154+
expectDeprecated(Timestamp.MAX_VALUE);
155+
expectDeprecated(Timestamp.fromInt);
156+
expectDeprecated(Timestamp.fromNumber);
157+
158+
// Deprecated instance members: Arithmetic
159+
expectDeprecated(timestamp.add);
160+
expectDeprecated(timestamp.subtract);
161+
expectDeprecated(timestamp.sub);
162+
expectDeprecated(timestamp.multiply);
163+
expectDeprecated(timestamp.mul);
164+
expectDeprecated(timestamp.divide);
165+
expectDeprecated(timestamp.div);
166+
expectDeprecated(timestamp.modulo);
167+
expectDeprecated(timestamp.mod);
168+
expectDeprecated(timestamp.rem);
169+
expectDeprecated(timestamp.negate);
170+
expectDeprecated(timestamp.neg);
171+
expectDeprecated(timestamp.comp);
172+
expectDeprecated(timestamp.isZero);
173+
expectDeprecated(timestamp.eqz);
174+
expectDeprecated(timestamp.high);
175+
expectDeprecated(timestamp.low);
176+
177+
// Deprecated instance members: Bitwise
178+
expectDeprecated(timestamp.and);
179+
expectDeprecated(timestamp.or);
180+
expectDeprecated(timestamp.xor);
181+
expectDeprecated(timestamp.not);
182+
expectDeprecated(timestamp.shiftLeft);
183+
expectDeprecated(timestamp.shl);
184+
expectDeprecated(timestamp.shiftRight);
185+
expectDeprecated(timestamp.shr);
186+
expectDeprecated(timestamp.shiftRightUnsigned);
187+
expectDeprecated(timestamp.shr_u);
188+
expectDeprecated(timestamp.shru);
189+
190+
// Deprecated instance members: Signing
191+
expectDeprecated(timestamp.toSigned);
192+
expectDeprecated(timestamp.toUnsigned);
193+
expectDeprecated(timestamp.isNegative);
194+
expectDeprecated(timestamp.isPositive);
195+
expectDeprecated(timestamp.unsigned);
196+
197+
// Deprecated instance members: Conversion
198+
expectDeprecated(timestamp.toInt);
199+
expectDeprecated(timestamp.toNumber);
200+
expectDeprecated(timestamp.toBytes);
201+
expectDeprecated(timestamp.toBytesLE);
202+
expectDeprecated(timestamp.toBytesBE);
203+
204+
// Deprecated instance members: Other
205+
expectDeprecated(timestamp.getHighBits);
206+
expectDeprecated(timestamp.getHighBitsUnsigned);
207+
expectDeprecated(timestamp.getLowBits);
208+
expectDeprecated(timestamp.getLowBitsUnsigned);
209+
expectDeprecated(timestamp.__isLong__);
210+
expectDeprecated(timestamp.getNumBitsAbs);
211+
expectDeprecated(timestamp.isEven);
212+
expectDeprecated(timestamp.isOdd);

0 commit comments

Comments
 (0)