Skip to content

Commit dd10ed7

Browse files
yvonnep165yvonnep165
authored
fix(firestore): Refactor the parameters for timestamp expressions and fix bug for timeGranularity lowercase (#9750)
* Add timestampTrunc, timestampDiff and timestampExtract expressions * Add changeset * Fix formatting * Fix variable names to follow camelCase * Generate documentation * Fix the int64 documentation error * Fix formatting * Add a test for isoWeek for timestampTruncate * Refactor the parameters for timestamp expressions and change all timegranularity value to lowercase * Remove duplicate timePart variables * Fix documentation error
1 parent 334b266 commit dd10ed7

11 files changed

Lines changed: 185 additions & 220 deletions

‎.changeset/orange-schools-bake.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
'firebase': patch
3+
'@firebase/firestore': patch
4+
---
5+
6+
Refactor the parameters for timestamp expressions and change all timegranularity value to lowercase

‎common/api-review/firestore-lite-pipelines.api.md‎

Lines changed: 15 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -762,19 +762,19 @@ export abstract class Expression {
762762
/* Excluded from this release type: _readUserData */
763763
timestampAdd(unit: Expression, amount: Expression): FunctionExpression;
764764
/* Excluded from this release type: _readUserData */
765-
timestampAdd(unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number): FunctionExpression;
765+
timestampAdd(unit: TimeUnit, amount: number): FunctionExpression;
766766
/* Excluded from this release type: _readUserData */
767767
timestampDiff(start: Expression, unit: Expression): FunctionExpression;
768768
/* Excluded from this release type: _readUserData */
769-
timestampDiff(start: string | Expression, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day'): FunctionExpression;
769+
timestampDiff(start: string | Expression, unit: TimeUnit): FunctionExpression;
770770
/* Excluded from this release type: _readUserData */
771771
timestampExtract(part: TimePart, timezone?: string | Expression): FunctionExpression;
772772
/* Excluded from this release type: _readUserData */
773773
timestampExtract(part: Expression, timezone?: string | Expression): FunctionExpression;
774774
/* Excluded from this release type: _readUserData */
775775
timestampSubtract(unit: Expression, amount: Expression): FunctionExpression;
776776
/* Excluded from this release type: _readUserData */
777-
timestampSubtract(unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number): FunctionExpression;
777+
timestampSubtract(unit: TimeUnit, amount: number): FunctionExpression;
778778
/* Excluded from this release type: _readUserData */
779779
timestampToUnixMicros(): FunctionExpression;
780780
/* Excluded from this release type: _readUserData */
@@ -1487,7 +1487,7 @@ export function sum(fieldName: string): AggregateFunction;
14871487
export function switchOn(condition: BooleanExpression, result: Expression, ...others: Array<BooleanExpression | Expression>): FunctionExpression;
14881488

14891489
// @beta
1490-
export type TimeGranularity = 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'week(monday)' | 'week(tuesday)' | 'week(wednesday)' | 'week(thursday)' | 'week(friday)' | 'week(saturday)' | 'week(sunday)' | 'isoWeek' | 'month' | 'quarter' | 'year' | 'isoYear';
1490+
export type TimeGranularity = TimeUnit | 'week' | 'week(monday)' | 'week(tuesday)' | 'week(wednesday)' | 'week(thursday)' | 'week(friday)' | 'week(saturday)' | 'week(sunday)' | 'isoweek' | 'month' | 'quarter' | 'year' | 'isoyear';
14911491

14921492
// @beta
14931493
export type TimePart = TimeGranularity | 'dayofweek' | 'dayofyear';
@@ -1496,22 +1496,22 @@ export type TimePart = TimeGranularity | 'dayofweek' | 'dayofyear';
14961496
export function timestampAdd(timestamp: Expression, unit: Expression, amount: Expression): FunctionExpression;
14971497

14981498
// @beta
1499-
export function timestampAdd(timestamp: Expression, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number): FunctionExpression;
1499+
export function timestampAdd(timestamp: Expression, unit: TimeUnit, amount: number): FunctionExpression;
15001500

15011501
// @beta
1502-
export function timestampAdd(fieldName: string, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number): FunctionExpression;
1502+
export function timestampAdd(fieldName: string, unit: TimeUnit, amount: number): FunctionExpression;
15031503

15041504
// @beta
1505-
export function timestampDiff(endFieldName: string, startFieldName: string, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | Expression): FunctionExpression;
1505+
export function timestampDiff(endFieldName: string, startFieldName: string, unit: TimeUnit | Expression): FunctionExpression;
15061506

15071507
// @beta
1508-
export function timestampDiff(endFieldName: string, startExpression: Expression, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | Expression): FunctionExpression;
1508+
export function timestampDiff(endFieldName: string, startExpression: Expression, unit: TimeUnit | Expression): FunctionExpression;
15091509

15101510
// @beta
1511-
export function timestampDiff(endExpression: Expression, startFieldName: string, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | Expression): FunctionExpression;
1511+
export function timestampDiff(endExpression: Expression, startFieldName: string, unit: TimeUnit | Expression): FunctionExpression;
15121512

15131513
// @beta
1514-
export function timestampDiff(endExpression: Expression, startExpression: Expression, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | Expression): FunctionExpression;
1514+
export function timestampDiff(endExpression: Expression, startExpression: Expression, unit: TimeUnit | Expression): FunctionExpression;
15151515

15161516
// @beta
15171517
export function timestampExtract(fieldName: string, part: TimePart, timezone?: string | Expression): FunctionExpression;
@@ -1529,10 +1529,10 @@ export function timestampExtract(timestampExpression: Expression, part: Expressi
15291529
export function timestampSubtract(timestamp: Expression, unit: Expression, amount: Expression): FunctionExpression;
15301530

15311531
// @beta
1532-
export function timestampSubtract(timestamp: Expression, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number): FunctionExpression;
1532+
export function timestampSubtract(timestamp: Expression, unit: TimeUnit, amount: number): FunctionExpression;
15331533

15341534
// @beta
1535-
export function timestampSubtract(fieldName: string, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number): FunctionExpression;
1535+
export function timestampSubtract(fieldName: string, unit: TimeUnit, amount: number): FunctionExpression;
15361536

15371537
// @beta
15381538
export function timestampToUnixMicros(expr: Expression): FunctionExpression;
@@ -1564,6 +1564,9 @@ export function timestampTruncate(timestampExpression: Expression, granularity:
15641564
// @beta
15651565
export function timestampTruncate(timestampExpression: Expression, granularity: Expression, timezone?: string | Expression): FunctionExpression;
15661566

1567+
// @beta
1568+
export type TimeUnit = 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
1569+
15671570
// @beta
15681571
export function toLower(fieldName: string): FunctionExpression;
15691572

‎common/api-review/firestore-pipelines.api.md‎

Lines changed: 15 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -765,19 +765,19 @@ export abstract class Expression {
765765
/* Excluded from this release type: _readUserData */
766766
timestampAdd(unit: Expression, amount: Expression): FunctionExpression;
767767
/* Excluded from this release type: _readUserData */
768-
timestampAdd(unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number): FunctionExpression;
768+
timestampAdd(unit: TimeUnit, amount: number): FunctionExpression;
769769
/* Excluded from this release type: _readUserData */
770770
timestampDiff(start: Expression, unit: Expression): FunctionExpression;
771771
/* Excluded from this release type: _readUserData */
772-
timestampDiff(start: string | Expression, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day'): FunctionExpression;
772+
timestampDiff(start: string | Expression, unit: TimeUnit): FunctionExpression;
773773
/* Excluded from this release type: _readUserData */
774774
timestampExtract(part: TimePart, timezone?: string | Expression): FunctionExpression;
775775
/* Excluded from this release type: _readUserData */
776776
timestampExtract(part: Expression, timezone?: string | Expression): FunctionExpression;
777777
/* Excluded from this release type: _readUserData */
778778
timestampSubtract(unit: Expression, amount: Expression): FunctionExpression;
779779
/* Excluded from this release type: _readUserData */
780-
timestampSubtract(unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number): FunctionExpression;
780+
timestampSubtract(unit: TimeUnit, amount: number): FunctionExpression;
781781
/* Excluded from this release type: _readUserData */
782782
timestampToUnixMicros(): FunctionExpression;
783783
/* Excluded from this release type: _readUserData */
@@ -1529,7 +1529,7 @@ export function sum(fieldName: string): AggregateFunction;
15291529
export function switchOn(condition: BooleanExpression, result: Expression, ...others: Array<BooleanExpression | Expression>): FunctionExpression;
15301530

15311531
// @beta
1532-
export type TimeGranularity = 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'week(monday)' | 'week(tuesday)' | 'week(wednesday)' | 'week(thursday)' | 'week(friday)' | 'week(saturday)' | 'week(sunday)' | 'isoWeek' | 'month' | 'quarter' | 'year' | 'isoYear';
1532+
export type TimeGranularity = TimeUnit | 'week' | 'week(monday)' | 'week(tuesday)' | 'week(wednesday)' | 'week(thursday)' | 'week(friday)' | 'week(saturday)' | 'week(sunday)' | 'isoweek' | 'month' | 'quarter' | 'year' | 'isoyear';
15331533

15341534
// @beta
15351535
export type TimePart = TimeGranularity | 'dayofweek' | 'dayofyear';
@@ -1538,22 +1538,22 @@ export type TimePart = TimeGranularity | 'dayofweek' | 'dayofyear';
15381538
export function timestampAdd(timestamp: Expression, unit: Expression, amount: Expression): FunctionExpression;
15391539

15401540
// @beta
1541-
export function timestampAdd(timestamp: Expression, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number): FunctionExpression;
1541+
export function timestampAdd(timestamp: Expression, unit: TimeUnit, amount: number): FunctionExpression;
15421542

15431543
// @beta
1544-
export function timestampAdd(fieldName: string, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number): FunctionExpression;
1544+
export function timestampAdd(fieldName: string, unit: TimeUnit, amount: number): FunctionExpression;
15451545

15461546
// @beta
1547-
export function timestampDiff(endFieldName: string, startFieldName: string, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | Expression): FunctionExpression;
1547+
export function timestampDiff(endFieldName: string, startFieldName: string, unit: TimeUnit | Expression): FunctionExpression;
15481548

15491549
// @beta
1550-
export function timestampDiff(endFieldName: string, startExpression: Expression, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | Expression): FunctionExpression;
1550+
export function timestampDiff(endFieldName: string, startExpression: Expression, unit: TimeUnit | Expression): FunctionExpression;
15511551

15521552
// @beta
1553-
export function timestampDiff(endExpression: Expression, startFieldName: string, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | Expression): FunctionExpression;
1553+
export function timestampDiff(endExpression: Expression, startFieldName: string, unit: TimeUnit | Expression): FunctionExpression;
15541554

15551555
// @beta
1556-
export function timestampDiff(endExpression: Expression, startExpression: Expression, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | Expression): FunctionExpression;
1556+
export function timestampDiff(endExpression: Expression, startExpression: Expression, unit: TimeUnit | Expression): FunctionExpression;
15571557

15581558
// @beta
15591559
export function timestampExtract(fieldName: string, part: TimePart, timezone?: string | Expression): FunctionExpression;
@@ -1571,10 +1571,10 @@ export function timestampExtract(timestampExpression: Expression, part: Expressi
15711571
export function timestampSubtract(timestamp: Expression, unit: Expression, amount: Expression): FunctionExpression;
15721572

15731573
// @beta
1574-
export function timestampSubtract(timestamp: Expression, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number): FunctionExpression;
1574+
export function timestampSubtract(timestamp: Expression, unit: TimeUnit, amount: number): FunctionExpression;
15751575

15761576
// @beta
1577-
export function timestampSubtract(fieldName: string, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number): FunctionExpression;
1577+
export function timestampSubtract(fieldName: string, unit: TimeUnit, amount: number): FunctionExpression;
15781578

15791579
// @beta
15801580
export function timestampToUnixMicros(expr: Expression): FunctionExpression;
@@ -1606,6 +1606,9 @@ export function timestampTruncate(timestampExpression: Expression, granularity:
16061606
// @beta
16071607
export function timestampTruncate(timestampExpression: Expression, granularity: Expression, timezone?: string | Expression): FunctionExpression;
16081608

1609+
// @beta
1610+
export type TimeUnit = 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
1611+
16091612
// @beta
16101613
export function toLower(fieldName: string): FunctionExpression;
16111614

‎docs-devsite/firestore_lite_pipelines.expression.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4797,14 +4797,14 @@ Creates an expression that adds a specified amount of time to this timestamp exp
47974797
<b>Signature:</b>
47984798

47994799
```typescript
4800-
timestampAdd(unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number): FunctionExpression;
4800+
timestampAdd(unit: TimeUnit, amount: number): FunctionExpression;
48014801
```
48024802

48034803
#### Parameters
48044804

48054805
| Parameter | Type | Description |
48064806
| --- | --- | --- |
4807-
| unit | 'microsecond' \| 'millisecond' \| 'second' \| 'minute' \| 'hour' \| 'day' | The unit of time to add (e.g., "day", "hour"). |
4807+
| unit | [TimeUnit](./firestore_lite_pipelines.md#timeunit) | The unit of time to add (e.g., "day", "hour"). |
48084808
| amount | number | The amount of time to add. |
48094809

48104810
<b>Returns:</b>
@@ -4867,15 +4867,15 @@ Creates an expression that calculates the difference between this timestamp and
48674867
<b>Signature:</b>
48684868

48694869
```typescript
4870-
timestampDiff(start: string | Expression, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day'): FunctionExpression;
4870+
timestampDiff(start: string | Expression, unit: TimeUnit): FunctionExpression;
48714871
```
48724872

48734873
#### Parameters
48744874

48754875
| Parameter | Type | Description |
48764876
| --- | --- | --- |
48774877
| start | string \| [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The field name of the starting timestamp. |
4878-
| unit | 'microsecond' \| 'millisecond' \| 'second' \| 'minute' \| 'hour' \| 'day' | The unit of time for the difference (e.g., "day", "hour"). |
4878+
| unit | [TimeUnit](./firestore_lite_pipelines.md#timeunit) | The unit of time for the difference (e.g., "day", "hour"). |
48794879

48804880
<b>Returns:</b>
48814881

@@ -5007,14 +5007,14 @@ Creates an expression that subtracts a specified amount of time from this timest
50075007
<b>Signature:</b>
50085008

50095009
```typescript
5010-
timestampSubtract(unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number): FunctionExpression;
5010+
timestampSubtract(unit: TimeUnit, amount: number): FunctionExpression;
50115011
```
50125012

50135013
#### Parameters
50145014

50155015
| Parameter | Type | Description |
50165016
| --- | --- | --- |
5017-
| unit | 'microsecond' \| 'millisecond' \| 'second' \| 'minute' \| 'hour' \| 'day' | The unit of time to subtract (e.g., "day", "hour"). |
5017+
| unit | [TimeUnit](./firestore_lite_pipelines.md#timeunit) | The unit of time to subtract (e.g., "day", "hour"). |
50185018
| amount | number | The amount of time to subtract. |
50195019

50205020
<b>Returns:</b>
@@ -5137,7 +5137,7 @@ timestampTruncate(granularity: TimeGranularity, timezone?: string | Expression):
51375137

51385138
[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
51395139

5140-
A new `Expression` representing the truncated timestamp.
5140+
A new [Expression](./firestore_pipelines.expression.md#expression_class) representing the truncated timestamp.
51415141

51425142
### Example
51435143

@@ -5172,7 +5172,7 @@ timestampTruncate(granularity: Expression, timezone?: string | Expression): Func
51725172

51735173
[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
51745174

5175-
A new `Expression` representing the truncated timestamp.
5175+
A new [Expression](./firestore_pipelines.expression.md#expression_class) representing the truncated timestamp.
51765176

51775177
### Example
51785178

0 commit comments

Comments
 (0)