@datalayer/core 0.0.9 → 0.0.11

package/lib/sdk/client/models/Runtime.js

@@ -0,0 +1,341 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * @module sdk/client/models/Runtime
+ * @description Runtime domain model for the Datalayer SDK.
+ *
+ * This model provides a rich, object-oriented interface for working with
+ * computational runtimes, including state management and lifecycle operations.
+ */
+import { updateRuntime } from '../../../api/runtimes/runtimes';
+/**
+ * Runtime domain model that wraps API responses with convenient methods.
+ *
+ * Provides a rich, object-oriented interface for managing computational runtimes
+ * with automatic state refresh and lifecycle operations.
+ *
+ * @example
+ * ```typescript
+ * const runtime = await sdk.createRuntime({
+ *   environment_name: 'python-cpu'
+ * });
+ *
+ * // Static properties - instant access
+ * console.log(runtime.podName);
+ * console.log(runtime.jupyterUrl);
+ *
+ * // Dynamic state - always fresh from API
+ * if (await runtime.isRunning()) {
+ *   console.log('Runtime is ready!');
+ * }
+ *
+ * // Wait for runtime to be ready
+ * await runtime.waitUntilReady();
+ *
+ * // Create snapshot
+ * const snapshot = await runtime.createSnapshot('my-snapshot');
+ * ```
+ */
+export class Runtime {
+    _data;
+    _sdk;
+    _deleted = false;
+    /**
+     * Create a Runtime instance.
+     *
+     * @param data - Raw runtime data from API
+     * @param sdk - DatalayerSDK instance for making API calls
+     */
+    constructor(data, sdk) {
+        this._data = data;
+        this._sdk = sdk;
+    }
+    // ========================================================================
+    // Helper Methods
+    // ========================================================================
+    /**
+     * Check if this runtime has been deleted and throw error if so.
+     * @throws Error if the runtime has been deleted
+     */
+    _checkDeleted() {
+        if (this._deleted) {
+            throw new Error(`Runtime ${this._data.pod_name} has been deleted and no longer exists`);
+        }
+    }
+    // ========================================================================
+    // Static Properties (set at creation, never change)
+    // ========================================================================
+    /**
+     * Kubernetes pod name for the runtime instance.
+     */
+    get podName() {
+        this._checkDeleted();
+        return this._data.pod_name;
+    }
+    /**
+     * Unique identifier for the runtime.
+     */
+    get uid() {
+        this._checkDeleted();
+        return this._data.uid;
+    }
+    /**
+     * Name of the environment this runtime is based on.
+     */
+    get environmentName() {
+        this._checkDeleted();
+        return this._data.environment_name;
+    }
+    /**
+     * URL for accessing Jupyter server.
+     */
+    get jupyterUrl() {
+        this._checkDeleted();
+        return this._data.jupyter_url || '';
+    }
+    /**
+     * Token for Jupyter server authentication.
+     */
+    get jupyterToken() {
+        this._checkDeleted();
+        return this._data.jupyter_token || '';
+    }
+    /**
+     * Credits consumed per hour.
+     */
+    get burningRate() {
+        this._checkDeleted();
+        return this._data.burning_rate;
+    }
+    /**
+     * User-friendly name for the runtime.
+     */
+    get givenName() {
+        this._checkDeleted();
+        return this._data.given_name || '';
+    }
+    /**
+     * Type of runtime (notebook, terminal, or job).
+     */
+    get type() {
+        this._checkDeleted();
+        return this._data.type || 'notebook';
+    }
+    /**
+     * When the runtime was created.
+     */
+    get createdAt() {
+        this._checkDeleted();
+        return new Date(this._data.created_at || '');
+    }
+    /**
+     * When the runtime started.
+     */
+    get startedAt() {
+        this._checkDeleted();
+        return new Date(this._data.started_at || '');
+    }
+    /**
+     * When the runtime will expire.
+     */
+    get expiredAt() {
+        this._checkDeleted();
+        return new Date(this._data.expired_at || '');
+    }
+    // ========================================================================
+    // Dynamic State (always fetches fresh and updates internal data)
+    // ========================================================================
+    /**
+     * Get the current state of the runtime.
+     *
+     * This method always fetches fresh data from the API and updates
+     * the internal data to keep everything in sync.
+     *
+     * @returns Promise resolving to current runtime state
+     * @throws Error if the runtime has been deleted
+     */
+    async getState() {
+        this._checkDeleted();
+        const freshRuntime = await this._sdk.getRuntime(this.podName);
+        // Update internal data with fresh runtime data
+        this._data = freshRuntime._data;
+        return this._data.state || 'unknown';
+    }
+    // ========================================================================
+    // State Checking Methods (always fresh)
+    // ========================================================================
+    /**
+     * Check if runtime is in running state.
+     *
+     * @returns Promise resolving to true if runtime is running
+     *
+     * @example
+     * ```typescript
+     * if (await runtime.isRunning()) {
+     *   console.log('Runtime is ready for use');
+     * }
+     * ```
+     */
+    async isRunning() {
+        return (await this.getState()) === 'running';
+    }
+    /**
+     * Check if runtime is in starting state.
+     *
+     * @returns Promise resolving to true if runtime is starting
+     */
+    async isStarting() {
+        return (await this.getState()) === 'starting';
+    }
+    /**
+     * Check if runtime is in stopping state.
+     *
+     * @returns Promise resolving to true if runtime is stopping
+     */
+    async isStopping() {
+        return (await this.getState()) === 'stopping';
+    }
+    /**
+     * Check if runtime is in stopped state.
+     *
+     * @returns Promise resolving to true if runtime is stopped
+     */
+    async isStopped() {
+        return (await this.getState()) === 'stopped';
+    }
+    /**
+     * Check if runtime is in error state.
+     *
+     * @returns Promise resolving to true if runtime has error
+     */
+    async hasError() {
+        return (await this.getState()) === 'error';
+    }
+    // ========================================================================
+    // Action Methods
+    // ========================================================================
+    /**
+     * Delete this runtime permanently.
+     *
+     * After deletion, this object will be marked as deleted and subsequent
+     * calls to dynamic methods will throw errors.
+     *
+     * @example
+     * ```typescript
+     * await runtime.delete();
+     * console.log('Runtime deleted');
+     * // runtime.getState() will now throw an error
+     * ```
+     */
+    async delete() {
+        await this._sdk.deleteRuntime(this.podName);
+        this._deleted = true;
+    }
+    /**
+     * Update runtime from a snapshot.
+     *
+     * @param from - Snapshot identifier to restore from
+     * @returns Promise resolving to updated Runtime instance
+     *
+     * @example
+     * ```typescript
+     * const updatedRuntime = await runtime.update('snapshot-uid');
+     * ```
+     */
+    async update(from) {
+        this._checkDeleted();
+        const updated = await updateRuntime(this._sdk.getToken(), this.podName, from, this._sdk.getRuntimesRunUrl());
+        return new Runtime(updated, this._sdk);
+    }
+    /**
+     * Create a snapshot of this runtime.
+     *
+     * @param name - Name for the snapshot
+     * @param description - Optional description for the snapshot
+     * @param stop - Whether to stop the runtime after snapshotting
+     * @returns Promise resolving to created Snapshot instance
+     *
+     * @example
+     * ```typescript
+     * const snapshot = await runtime.createSnapshot(
+     *   'my-checkpoint',
+     *   'Before major changes'
+     * );
+     * ```
+     */
+    async createSnapshot(name, description, stop) {
+        this._checkDeleted();
+        const request = {
+            pod_name: this.podName,
+            name,
+            description: description || '',
+            stop: stop || false,
+        };
+        // The SDK's createSnapshot already returns a Snapshot instance
+        return await this._sdk.createSnapshot(request);
+    }
+    /**
+     * Wait for runtime to reach running state.
+     *
+     * Polls the runtime state until it becomes 'running' or throws on error/timeout.
+     *
+     * @param timeoutMs - Maximum time to wait in milliseconds (default: 60000)
+     * @returns Promise resolving to this Runtime instance when ready
+     * @throws Error if runtime enters error state or timeout is reached
+     *
+     * @example
+     * ```typescript
+     * const runtime = await sdk.createRuntime(config);
+     * await runtime.waitUntilReady();
+     * console.log('Runtime is ready to use!');
+     * ```
+     */
+    async waitUntilReady(timeoutMs = 60000) {
+        this._checkDeleted();
+        const startTime = Date.now();
+        while (Date.now() - startTime < timeoutMs) {
+            if (await this.isRunning()) {
+                return this;
+            }
+            if (await this.hasError()) {
+                throw new Error(`Runtime ${this.podName} entered error state`);
+            }
+            // Wait 2 seconds before checking again
+            await new Promise(resolve => setTimeout(resolve, 2000));
+        }
+        throw new Error(`Timeout waiting for runtime ${this.podName} to be ready`);
+    }
+    // ========================================================================
+    // Utility Methods
+    // ========================================================================
+    /**
+     * Get raw runtime data object with latest state.
+     *
+     * This method ensures the returned data includes the most recent state
+     * by refreshing from the API before returning.
+     *
+     * @returns Promise resolving to raw runtime data
+     *
+     * @example
+     * ```typescript
+     * const latestData = await runtime.toJSON();
+     * console.log('Current state:', latestData.state);
+     * ```
+     */
+    async toJSON() {
+        this._checkDeleted();
+        await this.getState(); // This updates internal data
+        return this._data;
+    }
+    /**
+     * String representation of the runtime.
+     *
+     * @returns String representation for logging/debugging
+     */
+    toString() {
+        this._checkDeleted();
+        return `Runtime(${this.podName}, ${this.environmentName})`;
+    }
+}

package/lib/sdk/client/models/Snapshot.d.ts

@@ -0,0 +1,156 @@
+/**
+ * @module sdk/client/models/Snapshot
+ * @description Snapshot domain model for the Datalayer SDK.
+ *
+ * This model provides a rich, object-oriented interface for working with
+ * runtime snapshots, including fresh data fetching and lifecycle operations.
+ */
+import type { RuntimeSnapshot } from '../../../api/types/runtimes';
+import type { DatalayerSDK } from '../index';
+/**
+ * Snapshot domain model that wraps API responses with convenient methods.
+ *
+ * Provides a rich, object-oriented interface for managing runtime snapshots
+ * with automatic data refresh and lifecycle operations.
+ *
+ * @example
+ * ```typescript
+ * const snapshot = await runtime.createSnapshot('my-checkpoint', 'Before changes');
+ *
+ * // Static properties - instant access
+ * console.log(snapshot.uid);
+ * console.log(snapshot.environment);
+ *
+ * // Dynamic data - always fresh from API
+ * const currentStatus = await snapshot.getStatus();
+ * const size = await snapshot.getSize();
+ *
+ * // Delete snapshot
+ * await snapshot.delete();
+ *
+ * // Restore runtime from snapshot
+ * const runtime = await snapshot.restore();
+ * ```
+ */
+export declare class Snapshot {
+    protected _data: RuntimeSnapshot;
+    private _sdk;
+    private _deleted;
+    /**
+     * Create a Snapshot instance.
+     *
+     * @param data - Raw snapshot data from API
+     * @param sdk - DatalayerSDK instance for making API calls
+     */
+    constructor(data: RuntimeSnapshot, sdk: DatalayerSDK);
+    /**
+     * Check if this snapshot has been deleted and throw error if so.
+     * @throws Error if the snapshot has been deleted
+     */
+    private _checkDeleted;
+    /**
+     * Unique identifier for the snapshot.
+     */
+    get uid(): string;
+    /**
+     * Name of the snapshot.
+     */
+    get name(): string;
+    /**
+     * Description of the snapshot.
+     */
+    get description(): string;
+    /**
+     * Name of the environment used by the runtime.
+     */
+    get environment(): string;
+    /**
+     * Format of the snapshot.
+     */
+    get format(): string;
+    /**
+     * Format version of the snapshot.
+     */
+    get formatVersion(): string;
+    /**
+     * Snapshot metadata.
+     */
+    get metadata(): Record<string, any>;
+    /**
+     * When the snapshot was last updated.
+     */
+    get updatedAt(): Date;
+    /**
+     * Get the current status of the snapshot.
+     *
+     * This method always fetches fresh data from the API and updates
+     * the internal data to keep everything in sync.
+     *
+     * @returns Promise resolving to current snapshot status
+     * @throws Error if the snapshot has been deleted
+     */
+    getStatus(): Promise<string>;
+    /**
+     * Get the current size of the snapshot.
+     *
+     * @returns Promise resolving to snapshot size in bytes
+     */
+    getSize(): Promise<number>;
+    /**
+     * Get the latest metadata of the snapshot.
+     *
+     * @returns Promise resolving to snapshot metadata
+     */
+    getLatestMetadata(): Promise<Record<string, any>>;
+    /**
+     * Delete this snapshot permanently.
+     *
+     * After deletion, this object will be marked as deleted and subsequent
+     * calls to dynamic methods will throw errors.
+     *
+     * @example
+     * ```typescript
+     * await snapshot.delete();
+     * console.log('Snapshot deleted');
+     * // snapshot.getStatus() will now throw an error
+     * ```
+     */
+    delete(): Promise<void>;
+    /**
+     * Create a runtime from this snapshot (restore functionality).
+     *
+     * @param config - Optional runtime configuration to override defaults
+     * @returns Promise resolving to created Runtime instance
+     *
+     * @example
+     * ```typescript
+     * const runtime = await snapshot.restore({
+     *   credits_limit: 200
+     * });
+     * await runtime.waitUntilReady();
+     * ```
+     */
+    restore(config?: any): Promise<any>;
+    /**
+     * Get raw snapshot data object with latest information.
+     *
+     * This method ensures the returned data includes the most recent information
+     * by refreshing from the API before returning.
+     *
+     * @returns Promise resolving to raw snapshot data
+     *
+     * @example
+     * ```typescript
+     * const latestData = await snapshot.toJSON();
+     * console.log('Current status:', latestData.status);
+     * ```
+     */
+    toJSON(): Promise<RuntimeSnapshot>;
+    /**
+     * String representation of the snapshot.
+     *
+     * @returns String representation for logging/debugging
+     */
+    toString(): string;
+}
+export type { RuntimeSnapshot };