@datalayer/core 0.0.9 → 0.0.11

package/lib/sdk/client/utils/mixins.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @module sdk/client/utils/mixins
+ * @description TypeScript mixin utilities for composing the DatalayerSDK class.
+ */
+/**
+ * Type for a constructor function that can be used in mixins.
+ */
+export type Constructor<T = {}> = new (...args: any[]) => T;
+/**
+ * Apply mixins to a base class.
+ *
+ * This utility function enables multiple inheritance-like behavior in TypeScript
+ * by copying properties and methods from mixin classes to the target class.
+ *
+ * @param derivedCtor - The base class to extend
+ * @param constructors - Array of mixin classes to apply
+ *
+ * @example
+ * ```typescript
+ * class Base {
+ *   baseMethod() { return 'base'; }
+ * }
+ *
+ * class MixinA {
+ *   mixinAMethod() { return 'A'; }
+ * }
+ *
+ * class MixinB {
+ *   mixinBMethod() { return 'B'; }
+ * }
+ *
+ * interface Combined extends Base, MixinA, MixinB {}
+ * class Combined extends Base {}
+ * applyMixins(Combined, [MixinA, MixinB]);
+ *
+ * const instance = new Combined();
+ * instance.baseMethod(); // 'base'
+ * instance.mixinAMethod(); // 'A'
+ * instance.mixinBMethod(); // 'B'
+ * ```
+ */
+export declare function applyMixins(derivedCtor: any, constructors: any[]): void;

package/lib/sdk/client/utils/mixins.js

@@ -0,0 +1,47 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Apply mixins to a base class.
+ *
+ * This utility function enables multiple inheritance-like behavior in TypeScript
+ * by copying properties and methods from mixin classes to the target class.
+ *
+ * @param derivedCtor - The base class to extend
+ * @param constructors - Array of mixin classes to apply
+ *
+ * @example
+ * ```typescript
+ * class Base {
+ *   baseMethod() { return 'base'; }
+ * }
+ *
+ * class MixinA {
+ *   mixinAMethod() { return 'A'; }
+ * }
+ *
+ * class MixinB {
+ *   mixinBMethod() { return 'B'; }
+ * }
+ *
+ * interface Combined extends Base, MixinA, MixinB {}
+ * class Combined extends Base {}
+ * applyMixins(Combined, [MixinA, MixinB]);
+ *
+ * const instance = new Combined();
+ * instance.baseMethod(); // 'base'
+ * instance.mixinAMethod(); // 'A'
+ * instance.mixinBMethod(); // 'B'
+ * ```
+ */
+export function applyMixins(derivedCtor, constructors) {
+    constructors.forEach(baseCtor => {
+        Object.getOwnPropertyNames(baseCtor.prototype).forEach(name => {
+            if (name !== 'constructor') {
+                Object.defineProperty(derivedCtor.prototype, name, Object.getOwnPropertyDescriptor(baseCtor.prototype, name) ||
+                    Object.create(null));
+            }
+        });
+    });
+}

package/lib/sdk/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @module sdk
+ * @description Main SDK entry point for the Datalayer platform.
+ *
+ * This module provides the unified DatalayerSDK class with a flat, intuitive API
+ * for all Datalayer platform services. The SDK uses TypeScript mixins to provide
+ * excellent discoverability and ease of use.
+ *
+ * @example
+ * ```typescript
+ * import { DatalayerSDK } from '@datalayer/core/sdk';
+ *
+ * const sdk = new DatalayerSDK({
+ *   token: 'your-api-token',
+ *   baseUrl: 'https://prod1.datalayer.run'
+ * });
+ *
+ * // Flat, intuitive API - all methods directly accessible
+ * const user = await sdk.whoami();
+ * const environments = await sdk.listEnvironments();
+ * const runtime = await sdk.createRuntime(config);
+ * const notebook = await sdk.createNotebook(data);
+ * ```
+ */
+export { DatalayerSDK, type DatalayerSDKConfig } from './client';
+export * from './stateful';

package/lib/sdk/index.js

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * @module sdk
+ * @description Main SDK entry point for the Datalayer platform.
+ *
+ * This module provides the unified DatalayerSDK class with a flat, intuitive API
+ * for all Datalayer platform services. The SDK uses TypeScript mixins to provide
+ * excellent discoverability and ease of use.
+ *
+ * @example
+ * ```typescript
+ * import { DatalayerSDK } from '@datalayer/core/sdk';
+ *
+ * const sdk = new DatalayerSDK({
+ *   token: 'your-api-token',
+ *   baseUrl: 'https://prod1.datalayer.run'
+ * });
+ *
+ * // Flat, intuitive API - all methods directly accessible
+ * const user = await sdk.whoami();
+ * const environments = await sdk.listEnvironments();
+ * const runtime = await sdk.createRuntime(config);
+ * const notebook = await sdk.createNotebook(data);
+ * ```
+ */
+// Export the main SDK class with flat API
+export { DatalayerSDK } from './client';
+// Export stateful modules for advanced use cases
+export * from './stateful';

package/lib/sdk/stateful/index.d.ts

@@ -0,0 +1,3 @@
+export * from './jupyter';
+export * from './runtimes';
+export * from '../../api/DatalayerApi';

package/lib/sdk/stateful/index.js

@@ -0,0 +1,7 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export * from './jupyter';
+export * from './runtimes';
+export * from '../../api/DatalayerApi';

package/lib/{api → sdk/stateful}/runtimes/actions.d.ts

@@ -1,5 +1,5 @@
 import { IRuntimeOptions } from '..';
-import type { IRuntimeSnapshot, IDatalayerEnvironment, IRuntimePod } from '../../models';
+import type { IRuntimeSnapshot, IDatalayerEnvironment, IRuntimePod } from '../../../models';
 /**
  * Get available Environments.
  */

package/lib/{api → sdk/stateful}/runtimes/actions.js

@@ -9,9 +9,9 @@ import { URLExt } from '@jupyterlab/coreutils';
 import { PromiseDelegate } from '@lumino/coreutils';
 import { Upload } from 'tus-js-client';
 import { requestDatalayerAPI, } from '..';
-import { asRuntimeSnapshot } from '../../models';
-import { iamStore, runtimesStore } from '../../state';
-import { sleep } from '../../utils';
+import { asRuntimeSnapshot } from '../../../models';
+import { iamStore, runtimesStore } from '../../../state';
+import { sleep } from '../../../utils';
 /**
  * Get available Environments.
  */

package/lib/{api → sdk/stateful}/runtimes/apis.d.ts

@@ -5,7 +5,7 @@ import { ISessionContext } from '@jupyterlab/apputils';
 import { ServiceManager, Kernel, ServerConnection } from '@jupyterlab/services';
 import { IDisposable } from '@lumino/disposable';
 import { ISignal } from '@lumino/signaling';
-import type { IRuntimeSnapshot, IRuntimeCapabilities, IRuntimeModel, IDatalayerEnvironment, IRuntimeType, IRuntimeLocation } from '../../models';
+import type { IRuntimeSnapshot, IRuntimeCapabilities, IRuntimeModel, IDatalayerEnvironment, IRuntimeType, IRuntimeLocation } from '../../../models';
 /**
  * Abstract interface for the Datalayer session context.
  * It extends the JupyterLab session context

package/lib/sdk/stateful/runtimes/apis.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export {};

package/lib/sdk/stateful/runtimes/index.d.ts

@@ -0,0 +1,5 @@
+export * from './actions';
+export * from './apis';
+export * from './settings';
+export * from './snapshots';
+export * from './utils';

package/lib/sdk/stateful/runtimes/index.js

@@ -0,0 +1,9 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export * from './actions';
+export * from './apis';
+export * from './settings';
+export * from './snapshots';
+export * from './utils';

package/lib/sdk/stateful/runtimes/snapshots.d.ts

@@ -0,0 +1,25 @@
+import { Kernel } from '@jupyterlab/services';
+type Props = {
+    connection: Kernel.IKernelConnection;
+    metadata: {
+        filename: string;
+        [key: string]: string;
+    };
+    onUploadProgress?: (bytesUploaded: number, bytesTotal: number) => void;
+};
+/**
+ * Snapshot a runtime through the frontend and upload it to the cloud.
+ *
+ * Note: You should use this only for browser runtimes.
+ */
+export declare function createRuntimeSnapshot(props: Props): Promise<void>;
+/**
+ * Load a snapshot within a browser kernel.
+ *
+ * Note: You should use this only for browser kernels.
+ */
+export declare function loadBrowserRuntimeSnapshot({ connection, id, }: {
+    connection: Kernel.IKernelConnection;
+    id: string;
+}): Promise<void>;
+export {};

package/lib/sdk/stateful/runtimes/snapshots.js

@@ -0,0 +1,150 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { KernelExecutor } from '@datalayer/jupyter-react';
+import { createRuntimeSnapshotDownloadURL, uploadRuntimeSnapshot } from '.';
+/**
+ * Snapshot a runtime through the frontend and upload it to the cloud.
+ *
+ * Note: You should use this only for browser runtimes.
+ */
+export async function createRuntimeSnapshot(props) {
+    const { connection, metadata, onUploadProgress } = props;
+    const dump = await new KernelExecutor({ connection }).execute(GET_RUNTIME_SNAPSHOT_SNIPPET, {
+        storeHistory: false,
+    });
+    const serializedData = (dump.get(0)?.data['application/vnd.jupyter.stdout'] ??
+        '');
+    // Convert the data to blob.
+    const bytes = base64ToBytes(serializedData);
+    const file = new Blob([bytes.buffer]);
+    return uploadRuntimeSnapshot({
+        file,
+        metadata,
+        onProgress: onUploadProgress,
+    });
+}
+function base64ToBytes(base64) {
+    // Taken from https://developer.mozilla.org/en-US/docs/Web/API/Window/btoa#unicode_strings
+    const binString = atob(base64);
+    // @ts-expect-error TypeScript does not like this
+    return Uint8Array.from(binString, m => m.codePointAt(0));
+}
+/**
+ * Load a snapshot within a browser kernel.
+ *
+ * Note: You should use this only for browser kernels.
+ */
+export async function loadBrowserRuntimeSnapshot({ connection, id, }) {
+    const downloadURL = createRuntimeSnapshotDownloadURL(id);
+    const response = await fetch(downloadURL);
+    const buffer = await response.arrayBuffer();
+    const base64 = bytesToBase64(new Uint8Array(buffer));
+    await new KernelExecutor({
+        connection,
+    }).execute(getLoadRuntimeSnapshotSnippet(base64), {
+        storeHistory: false,
+        silent: true,
+    });
+}
+function bytesToBase64(bytes) {
+    // Taken from https://developer.mozilla.org/en-US/docs/Web/API/Window/btoa#unicode_strings
+    const binString = Array.from(bytes, byte => String.fromCodePoint(byte)).join('');
+    return btoa(binString);
+}
+const GET_RUNTIME_SNAPSHOT_SNIPPET = `def _create_snapshot():
+    import logging
+    import os
+    import pickle
+    from base64 import encodebytes
+    from tempfile import TemporaryFile
+    from types import BuiltinFunctionType, BuiltinMethodType, FunctionType, MethodType, MethodWrapperType, ModuleType, TracebackType
+    
+    # print(pickle.DEFAULT_PROTOCOL)
+
+    class NotFound:
+        pass
+
+    missing = NotFound()
+
+    FORBIDDEN_TYPES = [type, BuiltinFunctionType, BuiltinMethodType, FunctionType, MethodType, MethodWrapperType, ModuleType, TracebackType, NotFound]
+    try:
+        from IPython.core.autocall import ExitAutocall
+        from IPython.core.interactiveshell import InteractiveShell
+        FORBIDDEN_TYPES.extend([ExitAutocall, InteractiveShell])
+    except ImportError:
+        pass
+    exclude = tuple(FORBIDDEN_TYPES)
+
+    all = frozenset(filter(lambda n: not n.startswith("_"), globals()))
+
+    line_separator = bytes(os.linesep, "utf-8")
+    with TemporaryFile() as dump:
+        for _n in all:
+            _v = globals().get(_n, missing)
+            
+            if not (
+                isinstance(_v, exclude) or
+                # Special IPython variables
+                (_n == "In" and isinstance(_v, list)) or
+                (_n == "Out" and isinstance(_v, dict))
+            ):
+                try:
+                    dumped_n = _n.encode("utf-8") + line_separator + pickle.dumps(_v) + line_separator + b"\\x00" + line_separator
+                    dump.write(dumped_n)
+                except BaseException as e:
+                    logging.warning("Failed to dump variable [%s ([%s])].", _n, type(_v).__qualname__, exc_info=e)
+                else:
+                    logging.debug("Variable [%s] dumped", _n)
+
+        dump.seek(0)
+        print(encodebytes(dump.read()).decode("ascii"))
+
+_create_snapshot()
+del _create_snapshot
+`;
+function getLoadRuntimeSnapshotSnippet(content) {
+    return `async def _load_snapshot():
+    import os
+    import logging
+    import platform
+    import pickle
+    from base64 import decodebytes
+    is_pyodide = platform.node() == "emscripten"
+
+    snapshot = decodebytes("${content}".encode("ascii"))
+    line_sep = bytes(os.linesep, "utf-8")
+    variable_separator = b"\\x00" + line_sep
+    name = b""
+    value = b""
+    for line in snapshot.splitlines():
+        line += line_sep
+        if line == variable_separator:
+            name_s = name.strip().decode("utf-8")
+            try:
+                try:
+                    globals()[name_s] = pickle.loads(value)
+                except ModuleNotFoundError as m:
+                    if is_pyodide:
+                        import micropip
+                        logging.info(f'Installing %s...', m.name)
+                        await micropip.install(m.name)
+                        globals()[name_s] = pickle.loads(value)
+                    else:
+                        raise m
+            except BaseException as e:
+                logging.warning("Failed to load variable [%s].", name_s, exc_info=e)
+            else:
+                logging.debug("Variable [%s] loaded", name_s)
+
+            name = b""
+            value = b""
+        else:
+            if not name:
+                name = line
+            else:
+                value += line
+await _load_snapshot()
+del _load_snapshot`;
+}

package/lib/services/DatalayerServiceManager.js

@@ -5,7 +5,7 @@
 import { ServerConnection, ServiceManager } from '@jupyterlab/services';
 import { coreStore } from '../state/substates/CoreState';
 import { DEFAULT_DATALAYER_CONFIG } from '../config/Configuration';
-import { createRuntime } from '../api/runtimes/actions';
+import { createRuntime } from '../sdk/stateful/runtimes/actions';
 /**
  * Creates a ServiceManager configured for Datalayer.
  *

package/lib/state/substates/IAMState.js

@@ -7,7 +7,7 @@ import { useStore } from 'zustand';
 import { createStore } from 'zustand/vanilla';
 import { ANONYMOUS_USER_TOKEN, ANONYMOUS_USER, asUser, IAMProvidersSpecs, } from '../../models';
 import { getStoredToken, getStoredUser, loadRefreshTokenFromCookie, storeToken, storeUser, } from '../storage';
-import { requestDatalayerAPI } from '../../api';
+import { requestDatalayerAPI, } from '../../api/DatalayerApi';
 import { getCookie, setCookie, deleteCookie } from '../../utils';
 import { coreStore } from './CoreState';
 /**

package/lib/state/substates/RuntimesState.d.ts

@@ -1,4 +1,4 @@
-import type { IMultiServiceManager } from '../../api';
+import type { IMultiServiceManager } from '../../sdk/stateful/runtimes';
 import type { IRuntimesConfiguration } from '../../config';
 import type { IRuntimePod, IRuntimeSnapshot, IRuntimeModel } from '../../models';
 /**

package/lib/state/substates/RuntimesState.js

@@ -6,7 +6,7 @@ import { useStore } from 'zustand';
 import { createStore } from 'zustand/vanilla';
 import { JSONExt } from '@lumino/coreutils';
 import { Poll } from '@lumino/polling';
-import { getRuntimes } from '../../api';
+import { getRuntimes } from '../../sdk/stateful/runtimes';
 import { coreStore } from './CoreState';
 import { iamStore } from './IAMState';
 /**

package/lib/state/substates/SurveysState.js

@@ -4,7 +4,7 @@
  */
 import { createStore } from 'zustand/vanilla';
 import { useStore } from 'zustand';
-import { requestDatalayerAPI } from '../../api';
+import { requestDatalayerAPI, } from '../../api/DatalayerApi';
 import { asSurvey, } from '../../models';
 import { coreStore } from './CoreState';
 import { iamStore } from './IAMState';

package/lib/test-setup.js

@@ -6,6 +6,7 @@
 // Add any global test configuration here
 // Define webpack globals that are expected by some dependencies
 global.__webpack_public_path__ = '';
+// Native FormData and fetch should work in Node.js 20+
 // Define other globals that might be needed
 global.global = globalThis;
 // Mock DragEvent and other DOM APIs not available in jsdom

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datalayer/core",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "type": "module",
   "workspaces": [
     ".",
@@ -47,16 +47,21 @@
     "dev": "vite",
     "build": "gulp resources-to-lib && tsc -b && vite build",
     "build:lib": "gulp resources-to-lib && tsc -b",
+    "build:types": "tsc -b",
     "build:nextjs": "npm run build --workspace=nextjs-notebook-example",
-    "build:electron": "npm run build --workspace=@datalayer/electron-example",
+    "build:electron": "npm run build --workspace=@datalayer/desktop",
     "build:examples": "npm run build:nextjs && npm run build:electron",
     "build:all": "npm run build && npm run build:examples",
     "lint": "eslint . --quiet",
     "lint:fix": "eslint . --fix",
     "lint:all": "npm run lint && npm run lint --workspaces --if-present",
+    "lint:fix:all": "npm run lint:fix && npm run lint:fix --workspaces --if-present",
     "format": "prettier --write \"src/**/*.{js,jsx,ts,tsx,css,json,md}\" \"examples/**/*.{js,jsx,ts,tsx,css,json,md,mjs}\"",
     "format:check": "prettier --check \"src/**/*.{js,jsx,ts,tsx,css,json,md}\" \"examples/**/*.{js,jsx,ts,tsx,css,json,md,mjs}\"",
+    "format:fix": "npm run format",
     "format:all": "npm run format && npm run format --workspaces --if-present",
+    "format:check:all": "npm run format:check && npm run format:check --workspaces --if-present",
+    "format:fix:all": "npm run format:all",
     "type-check": "tsc --noEmit",
     "type-check:all": "npm run type-check && npm run type-check --workspaces --if-present",
     "check": "npm run format:check && npm run lint:all && npm run type-check:all",
@@ -64,17 +69,20 @@
     "preview": "vite preview",
     "start": "vite",
     "clean": "rimraf lib tsconfig.tsbuildinfo",
-    "test": "vitest run --project=unit",
-    "test:watch": "vitest --project=unit",
-    "test:ui": "vitest --ui --project=unit",
-    "test:coverage": "vitest run --coverage --project=unit",
-    "test:storybook": "vitest run --project=storybook",
+    "test": "vitest run --project=unit --project=general",
+    "test:watch": "vitest --project=unit --project=general",
+    "test:ui": "vitest --ui --project=unit --project=general",
+    "test:coverage": "vitest run --coverage --project=unit --project=general",
+    "test:unit": "vitest run --project=unit",
+    "test:integration": "vitest run --project=integration",
+    "test:all": "vitest run",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
     "typedoc": "typedoc --options typedoc.json --out docs/docs/typescript_api",
     "watch:lib": "run-p 'watch:lib:*'",
     "watch:lib:res": "gulp resources-to-lib-watch",
-    "watch:lib:src": "tsc -b -w",
+    "watch:lib:src": "echo 'Type checking moved to separate command. Use npm run type-check:watch'",
+    "type-check:watch": "tsc -b -w --noEmit",
     "example": "vite --config vite.examples.config.ts",
     "example:nextjs": "npm run dev --workspace=nextjs-notebook-example",
     "example:electron": "cd examples/electron && npm run dev",
@@ -128,7 +136,6 @@
   "devDependencies": {
     "@chromatic-com/storybook": "^4.1.0",
     "@eslint/js": "^9.29.0",
-    "react-router-dom": "^6.22.3",
     "@storybook/addon-a11y": "^9.1.1",
     "@storybook/addon-docs": "^9.1.1",
     "@storybook/addon-onboarding": "^9.1.1",
@@ -141,7 +148,9 @@
     "@vitejs/plugin-react": "^4.5.2",
     "@vitest/browser": "^3.2.4",
     "@vitest/coverage-v8": "^3.2.4",
+    "abort-controller": "^3.0.0",
     "crypto-browserify": "^3.12.1",
+    "dotenv": "^17.2.2",
     "eslint": "^9.29.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",
@@ -160,6 +169,7 @@
     "npm-run-all": "^4.1.5",
     "playwright": "^1.53.2",
     "prettier": "^3.6.2",
+    "react-router-dom": "^6.22.3",
     "rimraf": "^6.0.1",
     "storybook": "^9.1.1",
     "typedoc-plugin-markdown": "^4.0.0",