Initial implementation for the store

edocsss · edocsss · commit 6f3ddd7f3b84 · 2025-03-02T22:29:17.000+08:00
diff --git a/src/google/utils/date.ts b/src/google/utils/date.ts
@@ -0,0 +1,7 @@
+/**
+ * Returns the current time in milliseconds since Unix epoch
+ * @returns number - Current timestamp in milliseconds
+ */
+export function getCurrentTimeMs(): number {
+    return Date.now();
+}
diff --git a/src/google/utils/range.ts b/src/google/utils/range.ts
@@ -0,0 +1,87 @@
+/**
+ * Combines sheet name and range into A1 notation
+ * 
+ * @param sheetName - Name of the sheet
+ * @param range - Range in A1 notation without sheet name
+ * @returns Complete A1 notation with sheet name
+ */
+export function getA1Range(sheetName: string, range: string): string {
+    return `${sheetName}!${range}`;
+}
+
+/**
+ * Represents a column index with its A1 notation name and numeric index
+ */
+export interface ColIdx {
+    name: string;
+    idx: number;
+}
+
+/**
+ * Maps column identifiers to their A1 notation and index information
+ */
+export class ColsMapping {
+    private mapping: Map<string, ColIdx>;
+
+    constructor(mapping: Map<string, ColIdx>) {
+        this.mapping = mapping;
+    }
+
+    public getNameMap(): Map<string, string> {
+        const entries = this.mapping.entries();
+        return new Map<string, string>(
+            Array.from(entries).map(([key, value]) => [key, value.name])
+        );
+    }
+}
+
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+
+/**
+ * Generates A1 notation column mapping for given column identifiers
+ * 
+ * @param columns - Array of column identifiers
+ * @returns Mapping of column identifiers to their A1 notation and index
+ */
+export function generateColumnMapping(columns: string[]): Map<string, ColIdx> {
+    return new Map(
+        columns.map((col, idx) => [
+            col,
+            {
+                name: generateColumnName(idx),
+                idx,
+            },
+        ])
+    );
+}
+
+/**
+ * Converts a zero-based index to A1 notation column name
+ * 
+ * @param n - Zero-based column index
+ * @returns Column name in A1 notation (e.g., A, B, ..., Z, AA, AB, etc.)
+ * 
+ * @example
+ * ```typescript
+ * generateColumnName(0)  // returns "A"
+ * generateColumnName(25) // returns "Z"
+ * generateColumnName(26) // returns "AA"
+ * generateColumnName(27) // returns "AB"
+ * ```
+ */
+export function generateColumnName(n: number): string {
+    // This is not a pure Base26 conversion since the second char can start from "A" (or 0) again.
+    // In a normal Base26 int to string conversion, the second char can only start from "B" (or 1).
+    // Hence, we need to handle the first digit separately from subsequent digits.
+    // For subsequent digits, we subtract 1 first to ensure they start from 0, not 1.
+    let col = ALPHABET[n % 26]!;
+    n = Math.floor(n / 26);
+
+    while (n > 0) {
+        n -= 1;
+        col = ALPHABET[n % 26]! + col;
+        n = Math.floor(n / 26);
+    }
+
+    return col;
+}
diff --git a/src/google/utils/values.ts b/src/google/utils/values.ts
@@ -0,0 +1,39 @@
+/**
+ * Escapes a value to ensure proper string representation in Google Sheets.
+ * Prefixes strings with a single quote to prevent automatic type conversion.
+ * 
+ * @param value - The value to escape
+ * @returns The escaped value
+ */
+export function escapeValue(value: any): any {
+    if (typeof value === 'string') {
+        return `'${value}`;
+    }
+    return value;
+}
+
+/**
+ * Error class for IEEE 754 safe integer boundary violations
+ */
+export class IEEE754SafeIntegerError extends Error {
+    constructor() {
+        super('Integer provided is not within the IEEE 754 safe integer boundary of [-(2^53), 2^53], the integer may have a precision loss');
+        this.name = 'IEEE754SafeIntegerError';
+    }
+}
+
+/**
+ * Checks if a numeric value is within IEEE 754 safe integer boundaries.
+ * 
+ * @param value - The value to check
+ * @throws {IEEE754SafeIntegerError} If the value is outside safe integer boundaries
+ */
+export function checkIEEE754SafeInteger(value: any): void {
+    if (typeof value !== 'number') {
+        return;
+    }
+
+    if (!Number.isSafeInteger(value)) {
+        throw new IEEE754SafeIntegerError();
+    }
+}
diff --git a/tests/google/utils/range.test.ts b/tests/google/utils/range.test.ts
@@ -0,0 +1,130 @@
+import {
+    getA1Range,
+    generateColumnName,
+    generateColumnMapping,
+    ColIdx,
+} from '../../../src/google/utils/range';
+
+describe('range', () => {
+    describe('getA1Range', () => {
+        it('should correctly combine sheet name and range', () => {
+            expect(getA1Range('sheet', 'A1:A50')).toBe('sheet!A1:A50');
+            expect(getA1Range('sheet', 'A1')).toBe('sheet!A1');
+            expect(getA1Range('sheet', 'A')).toBe('sheet!A');
+        });
+    });
+
+    describe('generateColumnName', () => {
+        interface TestCase {
+            name: string;
+            input: number;
+            expected: string;
+        }
+
+        const testCases: TestCase[] = [
+            {
+                name: 'zero',
+                input: 0,
+                expected: 'A',
+            },
+            {
+                name: 'single_character',
+                input: 15,
+                expected: 'P',
+            },
+            {
+                name: 'single_character_2',
+                input: 25,
+                expected: 'Z',
+            },
+            {
+                name: 'single_character_3',
+                input: 5,
+                expected: 'F',
+            },
+            {
+                name: 'double_character',
+                input: 26,
+                expected: 'AA',
+            },
+            {
+                name: 'double_character_2',
+                input: 52,
+                expected: 'BA',
+            },
+            {
+                name: 'double_character_3',
+                input: 89,
+                expected: 'CL',
+            },
+            {
+                name: 'max_column',
+                input: 18277,
+                expected: 'ZZZ',
+            },
+        ];
+
+        testCases.forEach(tc => {
+            it(tc.name, () => {
+                expect(generateColumnName(tc.input)).toBe(tc.expected);
+            });
+        });
+    });
+
+    describe('generateColumnMapping', () => {
+        interface TestCase {
+            name: string;
+            input: string[];
+            expected: Map<string, ColIdx>;
+        }
+
+        const testCases: TestCase[] = [
+            {
+                name: 'single_column',
+                input: ['col1'],
+                expected: new Map([
+                    ['col1', { name: 'A', idx: 0 }],
+                ]),
+            },
+            {
+                name: 'three_column',
+                input: ['col1', 'col2', 'col3'],
+                expected: new Map([
+                    ['col1', { name: 'A', idx: 0 }],
+                    ['col2', { name: 'B', idx: 1 }],
+                    ['col3', { name: 'C', idx: 2 }],
+                ]),
+            },
+            {
+                name: 'many_column',
+                input: [
+                    'c1', 'c2', 'c3', 'c4', 'c5', 'c6', 'c7', 'c8', 'c9', 'c10',
+                    'c11', 'c12', 'c13', 'c14', 'c15', 'c16', 'c17', 'c18', 'c19', 'c20',
+                    'c21', 'c22', 'c23', 'c24', 'c25', 'c26', 'c27', 'c28',
+                ],
+                expected: new Map([
+                    ['c1', { name: 'A', idx: 0 }], ['c2', { name: 'B', idx: 1 }],
+                    ['c3', { name: 'C', idx: 2 }], ['c4', { name: 'D', idx: 3 }],
+                    ['c5', { name: 'E', idx: 4 }], ['c6', { name: 'F', idx: 5 }],
+                    ['c7', { name: 'G', idx: 6 }], ['c8', { name: 'H', idx: 7 }],
+                    ['c9', { name: 'I', idx: 8 }], ['c10', { name: 'J', idx: 9 }],
+                    ['c11', { name: 'K', idx: 10 }], ['c12', { name: 'L', idx: 11 }],
+                    ['c13', { name: 'M', idx: 12 }], ['c14', { name: 'N', idx: 13 }],
+                    ['c15', { name: 'O', idx: 14 }], ['c16', { name: 'P', idx: 15 }],
+                    ['c17', { name: 'Q', idx: 16 }], ['c18', { name: 'R', idx: 17 }],
+                    ['c19', { name: 'S', idx: 18 }], ['c20', { name: 'T', idx: 19 }],
+                    ['c21', { name: 'U', idx: 20 }], ['c22', { name: 'V', idx: 21 }],
+                    ['c23', { name: 'W', idx: 22 }], ['c24', { name: 'X', idx: 23 }],
+                    ['c25', { name: 'Y', idx: 24 }], ['c26', { name: 'Z', idx: 25 }],
+                    ['c27', { name: 'AA', idx: 26 }], ['c28', { name: 'AB', idx: 27 }],
+                ]),
+            },
+        ];
+
+        testCases.forEach(tc => {
+            it(tc.name, () => {
+                expect(generateColumnMapping(tc.input)).toEqual(tc.expected);
+            });
+        });
+    });
+});
diff --git a/tests/google/utils/values.test.ts b/tests/google/utils/values.test.ts
@@ -0,0 +1,61 @@
+import {
+    escapeValue,
+    checkIEEE754SafeInteger,
+    IEEE754SafeIntegerError,
+} from '../../../src/google/utils/values';
+
+describe('values', () => {
+    describe('escapeValue', () => {
+        it('should escape string values with a leading quote', () => {
+            expect(escapeValue('blah')).toBe("'blah");
+        });
+
+        it('should not modify non-string values', () => {
+            expect(escapeValue(1)).toBe(1);
+            expect(escapeValue(true)).toBe(true);
+            expect(escapeValue(null)).toBe(null);
+            expect(escapeValue(undefined)).toBe(undefined);
+            expect(escapeValue({ key: 'value' })).toEqual({ key: 'value' });
+        });
+    });
+
+    describe('checkIEEE754SafeInteger', () => {
+        it('should accept zero as a safe integer', () => {
+            expect(() => checkIEEE754SafeInteger(0)).not.toThrow();
+        });
+
+        it('should accept integers within safe bounds', () => {
+            // Test lower bound: -(2^53)
+            expect(() => checkIEEE754SafeInteger(-9007199254740991)).not.toThrow();
+
+            // Test upper bound: 2^53
+            expect(() => checkIEEE754SafeInteger(9007199254740991)).not.toThrow();
+
+            // Test some regular integers
+            expect(() => checkIEEE754SafeInteger(42)).not.toThrow();
+            expect(() => checkIEEE754SafeInteger(-42)).not.toThrow();
+        });
+
+        it('should reject integers outside safe bounds', () => {
+            // Test below lower bound: -(2^53) - 1
+            expect(() => checkIEEE754SafeInteger(-9007199254740993)).toThrow(IEEE754SafeIntegerError);
+
+            // Test above upper bound: (2^53) + 1
+            expect(() => checkIEEE754SafeInteger(9007199254740993)).toThrow(IEEE754SafeIntegerError);
+        });
+
+        it('should ignore non-numeric values', () => {
+            expect(() => checkIEEE754SafeInteger('blah')).not.toThrow();
+            expect(() => checkIEEE754SafeInteger(true)).not.toThrow();
+            expect(() => checkIEEE754SafeInteger([])).not.toThrow();
+            expect(() => checkIEEE754SafeInteger({})).not.toThrow();
+            expect(() => checkIEEE754SafeInteger(null)).not.toThrow();
+            expect(() => checkIEEE754SafeInteger(undefined)).not.toThrow();
+        });
+
+        it('should reject non-integer numbers', () => {
+            expect(() => checkIEEE754SafeInteger(3.14)).toThrow(IEEE754SafeIntegerError);
+            expect(() => checkIEEE754SafeInteger(-2.5)).toThrow(IEEE754SafeIntegerError);
+        });
+    });
+});
