@erinjs/core 1.0.0

package/core/packages/util/src/SnowflakeUtil.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest';
+import { SnowflakeUtil } from './SnowflakeUtil.js';
+
+describe('SnowflakeUtil', () => {
+  it('timestampFromSnowflake converts correctly', () => {
+    const ts = 1609459200000; // 2021-01-01
+    const snowflake = SnowflakeUtil.snowflakeFromTimestamp(ts);
+    const back = SnowflakeUtil.timestampFromSnowflake(snowflake);
+    expect(back).toBe(ts);
+  });
+
+  it('isValid accepts valid snowflakes', () => {
+    expect(SnowflakeUtil.isValid('1234567890123456789')).toBe(true);
+    expect(SnowflakeUtil.isValid('0')).toBe(true);
+  });
+
+  it('isValid rejects invalid snowflakes', () => {
+    expect(SnowflakeUtil.isValid('')).toBe(false);
+    expect(SnowflakeUtil.isValid('abc')).toBe(false);
+    expect(SnowflakeUtil.isValid('-1')).toBe(false);
+  });
+
+  it('deconstruct returns components', () => {
+    const result = SnowflakeUtil.deconstruct('1234567890123456789');
+    expect(result).toHaveProperty('timestamp');
+    expect(result).toHaveProperty('date');
+    expect(result).toHaveProperty('workerId');
+    expect(result).toHaveProperty('processId');
+    expect(result).toHaveProperty('increment');
+  });
+
+  it('snowflakeFromTimestamp round-trips', () => {
+    const ts = Date.now();
+    const snowflake = SnowflakeUtil.snowflakeFromTimestamp(ts);
+    const back = SnowflakeUtil.timestampFromSnowflake(snowflake);
+    expect(Math.floor(back / 1000)).toBe(Math.floor(ts / 1000));
+  });
+
+  it('dateFromSnowflake returns Date', () => {
+    const ts = 1609459200000;
+    const snowflake = SnowflakeUtil.snowflakeFromTimestamp(ts);
+    const date = SnowflakeUtil.dateFromSnowflake(snowflake);
+    expect(date).toBeInstanceOf(Date);
+    expect(date.getTime()).toBe(ts);
+  });
+
+  it('deconstruct returns correct component values', () => {
+    const sf = SnowflakeUtil.snowflakeFromTimestamp(1609459200000);
+    const d = SnowflakeUtil.deconstruct(sf);
+    expect(d.timestamp).toBe(1609459200000);
+    expect(d.date).toBeInstanceOf(Date);
+    expect(typeof d.workerId).toBe('number');
+    expect(typeof d.processId).toBe('number');
+    expect(typeof d.increment).toBe('number');
+  });
+
+  it('deconstruct throws for non-numeric string', () => {
+    expect(() => SnowflakeUtil.deconstruct('abc')).toThrow(TypeError);
+    expect(() => SnowflakeUtil.deconstruct('12.34')).toThrow(TypeError);
+  });
+
+  it('isValid rejects negative', () => {
+    expect(SnowflakeUtil.isValid('-123')).toBe(false);
+  });
+
+  it('isValid rejects too long', () => {
+    expect(SnowflakeUtil.isValid('1' + '0'.repeat(20))).toBe(false);
+  });
+});

package/core/packages/util/src/SnowflakeUtil.ts

@@ -0,0 +1,65 @@
+/** Fluxer epoch (2015-01-01 00:00:00 UTC) in milliseconds */
+export const FLUXER_EPOCH = 1420070400000n;
+
+/**
+ * Utilities for Fluxer snowflake IDs.
+ * Fluxer uses Twitter Snowflakes with a custom epoch.
+ */
+export class SnowflakeUtil {
+  static readonly EPOCH = FLUXER_EPOCH;
+
+  /**
+   * Converts a snowflake to a Unix timestamp in milliseconds.
+   */
+  static timestampFromSnowflake(snowflake: string): number {
+    return Number((BigInt(snowflake) >> 22n) + FLUXER_EPOCH);
+  }
+
+  /**
+   * Converts a snowflake to a Date.
+   */
+  static dateFromSnowflake(snowflake: string): Date {
+    return new Date(this.timestampFromSnowflake(snowflake));
+  }
+
+  /**
+   * Converts a Unix timestamp (ms) to a snowflake string.
+   * Useful for pagination (before/after).
+   */
+  static snowflakeFromTimestamp(timestamp: number): string {
+    return ((BigInt(timestamp) - FLUXER_EPOCH) << 22n).toString();
+  }
+
+  /**
+   * Deconstructs a snowflake into its components.
+   * @throws TypeError If snowflake is not a valid numeric string
+   */
+  static deconstruct(snowflake: string): {
+    timestamp: number;
+    date: Date;
+    workerId: number;
+    processId: number;
+    increment: number;
+  } {
+    let big: bigint;
+    try {
+      big = BigInt(snowflake);
+    } catch {
+      throw new TypeError('Invalid snowflake: must be a numeric string');
+    }
+    return {
+      timestamp: Number((big >> 22n) + FLUXER_EPOCH),
+      date: new Date(Number((big >> 22n) + FLUXER_EPOCH)),
+      workerId: Number((big >> 17n) & 0x1fn),
+      processId: Number((big >> 12n) & 0x1fn),
+      increment: Number(big & 0xfffn),
+    };
+  }
+
+  /**
+   * Checks if a string is a valid snowflake format (numeric string, 0 or positive).
+   */
+  static isValid(snowflake: string): boolean {
+    return /^(0|[1-9]\d*)$/.test(snowflake) && snowflake.length <= 20;
+  }
+}

package/core/packages/util/src/UserFlagsBitField.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest';
+import { UserFlagsBitField, UserFlagsBits } from './UserFlagsBitField.js';
+
+describe('UserFlagsBitField', () => {
+  it('creates with default 0', () => {
+    const bf = new UserFlagsBitField();
+    expect(bf.bitfield).toBe(0n);
+  });
+
+  it('has checks Staff flag', () => {
+    const bf = new UserFlagsBitField([UserFlagsBits.Staff]);
+    expect(bf.has(UserFlagsBits.Staff)).toBe(true);
+    expect(bf.has(UserFlagsBits.Partner)).toBe(false);
+  });
+
+  it('add and remove BugHunter', () => {
+    const bf = new UserFlagsBitField().add(UserFlagsBits.BugHunter).add(UserFlagsBits.Partner);
+    expect(bf.has(UserFlagsBits.BugHunter)).toBe(true);
+    bf.remove(UserFlagsBits.BugHunter);
+    expect(bf.has(UserFlagsBits.BugHunter)).toBe(false);
+  });
+
+  it('serialize returns flags object', () => {
+    const bf = new UserFlagsBitField([UserFlagsBits.FriendlyBot]);
+    const s = bf.serialize();
+    expect(s.FriendlyBot).toBe(true);
+  });
+
+  it('toArray returns enabled flag names', () => {
+    const bf = new UserFlagsBitField([UserFlagsBits.Staff, UserFlagsBits.Partner]);
+    const arr = bf.toArray();
+    expect(arr).toContain('Staff');
+    expect(arr).toContain('Partner');
+  });
+
+  it('throws for invalid flag', () => {
+    expect(() => new UserFlagsBitField('InvalidFlag' as 'Staff')).toThrow(RangeError);
+  });
+});

package/core/packages/util/src/UserFlagsBitField.ts

@@ -0,0 +1,48 @@
+import { BitField, type BitFieldResolvable } from './BitField.js';
+
+/**
+ * User flag bit values matching the API UserFlags schema (openapi.json).
+ * Values are int64; bit shifts used where within 32-bit range, literals otherwise.
+ * Note: BitField's has/add/remove use JS bitwise ops (32-bit); full values are for API serialization.
+ */
+export const UserFlagsBits = {
+  Staff: 1n << 0n,
+  CtpMember: 1n << 1n,
+  Partner: 1n << 2n,
+  BugHunter: 1n << 3n,
+  FriendlyBot: 1n << 4n,
+  FriendlyBotManualApproval: 1n << 5n,
+  HighGlobalRateLimit: 1n << 33n,
+  Deleted: 1n << 34n,
+  DisabledSuspiciousActivity: 1n << 35n,
+  SelfDeleted: 1n << 36n,
+  PremiumDiscriminator: 1n << 37n,
+  Disabled: 1n << 38n,
+  HasSessionStarted: 1n << 39n,
+  PremiumBadgeHidden: 1n << 40n,
+  PremiumBadgeMasked: 1n << 41n,
+  PremiumBadgeTimestampHidden: 1n << 42n,
+  PremiumBadgeSequenceHidden: 1n << 43n,
+  PremiumPerksSanitized: 1n << 44n,
+  PremiumPurchaseDisabled: 1n << 45n,
+  PremiumEnabledOverride: 1n << 46n,
+  RateLimitBypass: 1n << 47n,
+  ReportBanned: 1n << 48n,
+  VerifiedNotUnderage: 1n << 49n,
+  PendingManualVerification: 1n << 50n,
+  HasDismissedPremiumOnboarding: 1n << 51n,
+  UsedMobileClient: 1n << 52n,
+  AppStoreReviewer: 1n << 53n,
+  DmHistoryBackfilled: 1n << 54n,
+  HasRelationshipsIndexed: 1n << 55n,
+  MessagesByAuthorBackfilled: 1n << 56n,
+  StaffHidden: 1n << 57n,
+} as const;
+
+export type UserFlagsString = keyof typeof UserFlagsBits;
+
+export class UserFlagsBitField extends BitField<UserFlagsString> {
+  static override Flags = UserFlagsBits;
+}
+
+export type UserFlagsResolvable = BitFieldResolvable<UserFlagsString>;

package/core/packages/util/src/deprecation.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { emitDeprecationWarning } from './deprecation.js';
+
+describe('emitDeprecationWarning', () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+  const origProcess = globalThis.process;
+
+  beforeEach(() => {
+    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+    (globalThis as { process?: typeof origProcess }).process = origProcess;
+  });
+
+  it('emits a warning on first call', () => {
+    emitDeprecationWarning('Test.symbolFirst', 'Use X instead.');
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy).toHaveBeenCalledWith(
+      '[Fluxer] DeprecationWarning: Test.symbolFirst is deprecated. Use X instead.',
+    );
+  });
+
+  it('does not emit again for same symbol', () => {
+    emitDeprecationWarning('Test.symbolDedup', 'Use X instead.');
+    emitDeprecationWarning('Test.symbolDedup', 'Use X instead.');
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('emits for different symbols', () => {
+    emitDeprecationWarning('A', 'Msg A');
+    emitDeprecationWarning('B', 'Msg B');
+    expect(warnSpy).toHaveBeenCalledTimes(2);
+  });
+
+  it('suppresses when FLUXER_SUPPRESS_DEPRECATION=1', () => {
+    (globalThis as { process?: { env?: Record<string, string> } }).process = {
+      env: { FLUXER_SUPPRESS_DEPRECATION: '1' },
+    };
+    emitDeprecationWarning('Test.symbolFirst', 'Use X instead.');
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+});

package/core/packages/util/src/deprecation.ts

@@ -0,0 +1,28 @@
+/**
+ * Emit a one-time deprecation warning for a symbol.
+ * Warnings are suppressed when FLUXER_SUPPRESS_DEPRECATION=1.
+ *
+ * @param symbol - Unique key for this deprecation (e.g. 'ChannelManager.fetchMessage')
+ * @param message - Deprecation message (e.g. 'Use channel.messages.fetch() instead.')
+ */
+const warned = new Set<string>();
+
+function isSuppressed(): boolean {
+  try {
+    const g = typeof globalThis !== 'undefined' ? globalThis : (void 0 as unknown);
+    const proc =
+      g && typeof (g as Record<string, unknown>).process === 'object'
+        ? (g as { process?: { env?: Record<string, string> } }).process
+        : undefined;
+    return proc?.env?.FLUXER_SUPPRESS_DEPRECATION === '1';
+  } catch {
+    return false;
+  }
+}
+
+export function emitDeprecationWarning(symbol: string, message: string): void {
+  if (isSuppressed()) return;
+  if (warned.has(symbol)) return;
+  warned.add(symbol);
+  console.warn(`[Fluxer] DeprecationWarning: ${symbol} is deprecated. ${message}`);
+}