WorkoutWrite — @gj-kit/expo-workouts

A public interface from @gj-kit/expo-workouts/core. The signature below is taken directly from the 0.1.1 release declaration.

Verified import example

import { WorkoutWrite } from '@gj-kit/expo-workouts/core';

Signature, parameters, and return type

/**
 * Full-state input for `saveWorkout`. There is NO partial-update path: on Android an upsert that
 * omits the route DELETES the stored route, so the only safe contract is "send everything".
 */
interface WorkoutWrite {
    /**
     * A stable id this app owns — the idempotency key. Becomes HKMetadataKeySyncIdentifier /
     * Health Connect `clientRecordId`.
     * ⚠ Other apps CAN read this value on Android. Use an opaque UUID.
     * Must match `/^[A-Za-z0-9._:-]{1,120}$/`.
     */
    readonly id: string;
    /**
     * A safe integer >= 1, non-decreasing per `id`, that increases whenever the content changes.
     * Derive it from your own record's `updatedAt` (epoch ms) or from an edit counter.
     * ⚠ NEVER `Date.now()` at call time: a crash retry would write a fresh version and, on iOS, mint a
     *   second workout object and orphan the first one's samples and route.
     * An EQUAL version replaces the stored workout; a LOWER one throws `staleVersion` and writes nothing.
     */
    readonly version: number;
    /**
     * Nine members since owner decision ③. `'other'` is the documented lossy sink — it stores
     * OTHER_WORKOUT(0) / `.other`(3000) and the original activity is not recoverable.
     */
    readonly kind: WorkoutKind;
    /**
     * Drives the platform activity constant on write.
     * ⚠ On Android it is only representable for `running`, `cycling`, `swimming` and `rowing`; for
     *   every other kind it is silently dropped and reads back `undefined`. On iOS it is written to
     *   `HKMetadataKeyIndoorWorkout` for every kind — but only when you actually set it: leaving it
     *   `undefined` OMITS the key rather than writing `@NO`.
     */
    readonly indoor?: boolean | undefined;
    readonly startMs: number;
    /** Must be > `startMs` and <= now. */
    readonly endMs: number;
    readonly utcOffsetMin?: number | undefined;
    /** IANA zone id (e.g. `'Asia/Seoul'`). iOS metadata only; Android stores only the offset. */
    readonly timeZoneId?: string | undefined;
    readonly pauses?: readonly Pause[] | undefined;
    readonly laps?: readonly Lap[] | undefined;
    readonly distanceM?: number | undefined;
    readonly activeEnergyKcal?: number | undefined;
    readonly elevationGainM?: number | undefined;
    /** Omitted from the write when <= 0 — Health Connect throws on `StepsRecord(count = 0)`. */
    readonly steps?: number | undefined;
    /** Samples outside 1..300 bpm or outside `[startMs, endMs)` are dropped before writing. */
    readonly heartRate?: readonly HeartRateSample[] | undefined;
    /**
     * REQUIRED, and `'none'` is not the same call shape as an empty array.
     *
     * ⚠ This is the one place where forgetting a field DESTROYS user data: an Android upsert that
     *   omits the route while holding the route write scope DELETES the stored route. Making the field
     *   required turns that silent, irreversible mistake into a compile error, and `'none'` forces the
     *   intent to be stated out loud.
     * An empty array is `invalidArgument` — say `'none'`.
     */
    readonly route: readonly RoutePoint[] | 'none';
}

This declaration is the source of truth for parameters, optionality, generics, return values, and public union/type contracts. Check the package golden path and this subpath’s import conditions for required environment, permission, and error boundaries before calling it.

Release context

• Package: @gj-kit/expo-workouts
• Version: 0.1.1
• Public entry: ./core
• Source: GitHub