@stacksjs/desktop 0.2.6 → 0.2.8

package/dist/power.d.ts

@@ -0,0 +1,79 @@
+import type { Subprocess } from 'bun';
+/**
+ * Start preventing the system from sleeping.
+ *
+ * Spawns a `/usr/bin/caffeinate` process with the specified options.
+ * If caffeinate is already active, the previous instance is stopped first.
+ *
+ * @param options - Caffeinate configuration
+ * @returns A CaffeinateInstance for monitoring and controlling the session
+ */
+export declare function caffeinate(options?: CaffeinateOptions): CaffeinateInstance;
+/**
+ * Stop caffeinate and allow the system to sleep normally.
+ *
+ * @param instance - Specific instance to stop. If omitted, stops the current active instance.
+ */
+export declare function decaffeinate(instance?: CaffeinateInstance): void;
+/**
+ * Check if caffeinate is currently active.
+ */
+export declare function isCaffeinated(): boolean;
+/**
+ * Get the current caffeinate status.
+ */
+export declare function getCaffeinateStatus(): CaffeinateStatus;
+/**
+ * Format remaining caffeinate time as a human-readable string.
+ *
+ * @example
+ * ```typescript
+ * formatRemainingTime(instance) // "25:30" or "∞"
+ * ```
+ */
+export declare function formatRemainingTime(instance?: CaffeinateInstance | null): string;
+/**
+ * Get a formatted description of the caffeinate duration.
+ */
+export declare function formatDuration(minutes: number): string;
+// ============================================================================
+// Types
+// ============================================================================
+export declare interface CaffeinateOptions {
+  duration?: number
+  preventDisplaySleep?: boolean
+  preventIdleSleep?: boolean
+  preventSystemSleep?: boolean
+  preventDiskSleep?: boolean
+  assertUserActivity?: boolean
+}
+export declare interface CaffeinateInstance {
+  readonly pid: number
+  readonly startedAt: Date
+  readonly endsAt: Date | null
+  readonly options: CaffeinateOptions
+  readonly isActive: boolean
+  readonly remainingMs: number | null
+  readonly elapsedMs: number
+  stop(): void
+  onExpire(handler: () => void): void
+}
+export declare interface CaffeinateStatus {
+  active: boolean
+  instance: CaffeinateInstance | null
+  startedAt: Date | null
+  endsAt: Date | null
+  durationMinutes: number | null
+}
+declare class CaffeinateInstanceImpl implements CaffeinateInstance {
+  constructor(process: Subprocess, options: CaffeinateOptions);
+  get pid(): number;
+  get startedAt(): Date;
+  get endsAt(): Date | null;
+  get options(): CaffeinateOptions;
+  get isActive(): boolean;
+  get remainingMs(): number | null;
+  get elapsedMs(): number;
+  stop(): void;
+  onExpire(handler: () => void): void;
+}

package/dist/preferences.d.ts

@@ -0,0 +1,48 @@
+import { watch } from 'node:fs';
+/**
+ * Create a preferences store for your application.
+ *
+ * Preferences are stored as JSON in a platform-appropriate location:
+ * - macOS: ~/Library/Application Support/{name}/preferences.json
+ * - Windows: %APPDATA%/{name}/preferences.json
+ * - Linux: ~/.config/{name}/preferences.json
+ */
+export declare function createPreferences<T extends Record<string, unknown>>(options: PreferencesOptions<T>): Preferences<T>;
+// ============================================================================
+// Types
+// ============================================================================
+export declare interface PreferencesOptions<T extends Record<string, unknown>> {
+  name: string
+  defaults: T
+  path?: string
+  watch?: boolean
+}
+export declare interface Preferences<T extends Record<string, unknown>> {
+  get<K extends keyof T>(key: K): T[K]
+  set<K extends keyof T>(key: K, value: T[K]): void
+  getAll(): T
+  has(key: keyof T): boolean
+  delete(key: keyof T): void
+  reset(): void
+  onChange<K extends keyof T>(key: K, handler: (value: T[K], oldValue: T[K]) => void): () => void
+  onAnyChange(handler: (key: keyof T, value: unknown, oldValue: unknown) => void): () => void
+  readonly path: string
+  close(): void
+}
+declare type ChangeHandler = (key: string, value: unknown, oldValue: unknown) => void;
+// ============================================================================
+// Implementation
+// ============================================================================
+declare class PreferencesImpl<T extends Record<string, unknown>> implements Preferences<T> {
+  constructor(options: PreferencesOptions<T>);
+  get path(): string;
+  get<K extends keyof T>(key: K): T[K];
+  set<K extends keyof T>(key: K, value: T[K]): void;
+  getAll(): T;
+  has(key: keyof T): boolean;
+  delete(key: keyof T): void;
+  reset(): void;
+  onChange<K extends keyof T>(key: K, handler: (value: T[K], oldValue: T[K]) => void): () => void;
+  onAnyChange(handler: ChangeHandler): () => void;
+  close(): void;
+}

package/dist/timer.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Create a countdown timer.
+ */
+export declare function createTimer(options: TimerOptions): Timer;
+/**
+ * Create a repeating interval.
+ */
+export declare function createInterval(options: IntervalOptions): Interval;
+/**
+ * Create a simple delay/sleep promise.
+ */
+export declare function delay(ms: number): Promise<void>;
+/**
+ * Format milliseconds as a human-readable time string.
+ *
+ * @example
+ * ```typescript
+ * formatTime(90000)   // "1:30"
+ * formatTime(3661000) // "1:01:01"
+ * formatTime(45000)   // "0:45"
+ * ```
+ */
+export declare function formatTime(ms: number): string;
+/**
+ * Format milliseconds as a compact string for display.
+ *
+ * @example
+ * ```typescript
+ * formatCompact(90000)    // "1m 30s"
+ * formatCompact(3600000)  // "1h"
+ * formatCompact(7230000)  // "2h 0m"
+ * ```
+ */
+export declare function formatCompact(ms: number): string;
+/**
+ * Timer / Scheduling Utilities
+ *
+ * Provides a rich timer API for desktop applications — useful for
+ * Pomodoro timers, caffeinate countdowns, auto-save intervals, etc.
+ *
+ * @example
+ * ```typescript
+ * import { createTimer } from '@stacksjs/desktop'
+ *
+ * const timer = createTimer({
+ *   duration: 25 * 60 * 1000, // 25 minutes
+ *   onTick: (remaining) => {
+ *     console.log(`${Math.ceil(remaining / 1000)}s remaining`)
+ *   },
+ *   onComplete: () => {
+ *     console.log('Timer complete!')
+ *   },
+ * })
+ *
+ * timer.start()
+ *
+ * // Later...
+ * timer.pause()
+ * timer.resume()
+ * timer.stop()
+ * timer.reset()
+ * ```
+ */
+// ============================================================================
+// Types
+// ============================================================================
+export declare interface TimerOptions {
+  duration: number
+  onTick?: (remaining: number) => void
+  onComplete?: () => void
+  tickInterval?: number
+  autoStart?: boolean
+}
+export declare interface Timer {
+  start(): void
+  stop(): void
+  pause(): void
+  resume(): void
+  reset(): void
+  readonly isRunning: boolean
+  readonly isPaused: boolean
+  readonly isComplete: boolean
+  readonly remaining: number
+  readonly elapsed: number
+  readonly duration: number
+  readonly progress: number
+  onComplete(handler: () => void): () => void
+  onTick(handler: (remaining: number) => void): () => void
+}
+export declare interface IntervalOptions {
+  interval: number
+  handler: () => void
+  immediate?: boolean
+}
+export declare interface Interval {
+  start(): void
+  stop(): void
+  readonly isRunning: boolean
+}
+// ============================================================================
+// Timer Implementation
+// ============================================================================
+declare class TimerImpl implements Timer {
+  constructor(options: TimerOptions);
+  get isRunning(): boolean;
+  get isPaused(): boolean;
+  get isComplete(): boolean;
+  get remaining(): number;
+  get elapsed(): number;
+  get duration(): number;
+  get progress(): number;
+  start(): void;
+  stop(): void;
+  pause(): void;
+  resume(): void;
+  reset(): void;
+  onComplete(handler: () => void): () => void;
+  onTick(handler: (remaining: number) => void): () => void;
+}
+// ============================================================================
+// Interval Implementation
+// ============================================================================
+declare class IntervalImpl implements Interval {
+  constructor(options: IntervalOptions);
+  get isRunning(): boolean;
+  start(): void;
+  stop(): void;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/desktop",
   "type": "module",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Native desktop application framework for stx (powered by Craft)",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",