nodepyx 1.0.0

package/src/types/config.ts

@@ -0,0 +1,226 @@
+/**
+ * nodepyx — Core Configuration Types
+ * Full configuration interface for nodepyx runtime initialization.
+ */
+
+export type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+
+export interface VirtualenvConfig {
+  /** Path to virtualenv directory (e.g. './.nodepyx/venv') */
+  path: string;
+  /** Python packages to install (e.g. ['pandas', 'numpy', 'scikit-learn']) */
+  packages: string[];
+  /** Automatically install missing packages at startup */
+  autoInstall: boolean;
+  /** pip index URL override */
+  pipIndexUrl?: string;
+  /** Additional pip install args */
+  pipArgs?: string[];
+}
+
+export interface CondaConfig {
+  /** Name of the conda environment */
+  envName: string;
+  /** Path to conda executable */
+  condaPath?: string;
+  /** Channels to search for packages */
+  channels?: string[];
+  /** Packages to ensure are installed */
+  packages?: string[];
+}
+
+export interface GILConfig {
+  /**
+   * How often to release the GIL during long Python operations (microseconds).
+   * Lower values improve Node.js responsiveness at cost of Python throughput.
+   * Default: 5000 (5ms)
+   */
+  releaseInterval?: number;
+  /**
+   * Maximum time to wait for GIL acquisition before timing out (milliseconds).
+   * Default: 10000 (10s)
+   */
+  acquireTimeout?: number;
+}
+
+export interface ThreadPoolConfig {
+  /** Number of worker threads for Python execution. Default: 4 */
+  size?: number;
+  /** Max queue depth before backpressure is applied. Default: 1000 */
+  maxQueueSize?: number;
+  /** Thread idle timeout before shrinking pool (ms). Default: 30000 */
+  idleTimeout?: number;
+}
+
+export interface MemoryConfig {
+  /** Maximum Python heap size (e.g. '2GB', '512MB'). Default: '2GB' */
+  limit?: string;
+  /** Trigger Python GC when heap exceeds this threshold. Default: '1GB' */
+  gcThreshold?: string;
+  /** Enable leak detection in debug builds. Default: false */
+  leakDetection?: boolean;
+}
+
+export interface ProfilingConfig {
+  /** Enable CPU profiling. Default: false */
+  enabled?: boolean;
+  /** Output file for profile data */
+  outputFile?: string;
+  /** Sampling interval (microseconds). Default: 1000 */
+  samplingInterval?: number;
+}
+
+export interface nodepyxConfig {
+  /**
+   * Path to Python executable or virtualenv root.
+   * If not specified, auto-detects system Python.
+   * Examples: '/usr/bin/python3', './.venv', '/opt/conda/envs/myenv'
+   */
+  pythonPath?: string;
+
+  /**
+   * Virtualenv configuration — creates and manages a dedicated virtualenv.
+   * Takes precedence over pythonPath if specified.
+   */
+  virtualenv?: VirtualenvConfig;
+
+  /**
+   * Conda environment configuration.
+   * Takes precedence over virtualenv and pythonPath if specified.
+   */
+  conda?: CondaConfig;
+
+  /**
+   * Thread pool configuration for Python execution.
+   */
+  threadPool?: ThreadPoolConfig;
+
+  /**
+   * Legacy shorthand for threadPool.size.
+   * @deprecated Use threadPool.size instead.
+   */
+  threadPoolSize?: number;
+
+  /**
+   * Memory configuration for Python heap.
+   */
+  memory?: MemoryConfig;
+
+  /**
+   * Legacy shorthand for memory.limit.
+   * @deprecated Use memory.limit instead.
+   */
+  memoryLimit?: string;
+
+  /**
+   * Directory for TypeScript type stubs generated from Python modules.
+   * Default: './.nodepyx/stubs'
+   */
+  stubsDir?: string;
+
+  /**
+   * Log level for nodepyx internal logging.
+   * Default: 'warn'
+   */
+  logLevel?: LogLevel;
+
+  /**
+   * Profiling configuration.
+   */
+  profiling?: ProfilingConfig;
+
+  /**
+   * Legacy shorthand for profiling.enabled.
+   * @deprecated Use profiling.enabled instead.
+   */
+  enableProfiling?: boolean;
+
+  /**
+   * Timeout for individual Python calls (milliseconds).
+   * Default: 30000 (30s)
+   */
+  callTimeout?: number;
+
+  /**
+   * GIL (Global Interpreter Lock) management configuration.
+   */
+  gil?: GILConfig;
+
+  /**
+   * Additional Python sys.path entries.
+   * Inserted at sys.path[0] in order.
+   */
+  pythonPath_extra?: string[];
+
+  /**
+   * Environment variables to set for the Python interpreter.
+   */
+  env?: Record<string, string>;
+
+  /**
+   * Enable experimental features. Use with caution.
+   */
+  experimental?: {
+    /** Use SharedArrayBuffer for NumPy transfers. Default: true */
+    sharedArrayBuffer?: boolean;
+    /** Cache Proxy chain resolutions. Default: true */
+    proxyCache?: boolean;
+    /** Lazy attribute resolution. Default: true */
+    lazyResolution?: boolean;
+  };
+}
+
+/**
+ * Resolved and normalized configuration (all fields filled with defaults).
+ */
+export interface ResolvednodepyxConfig {
+  pythonExecutable: string;
+  pythonHome: string;
+  threadPoolSize: number;
+  maxQueueSize: number;
+  idleTimeout: number;
+  memoryLimit: string;
+  gcThreshold: string;
+  leakDetection: boolean;
+  stubsDir: string;
+  logLevel: LogLevel;
+  callTimeout: number;
+  gil: Required<GILConfig>;
+  profilingEnabled: boolean;
+  profilingFile?: string;
+  profilingSamplingInterval: number;
+  sharedArrayBuffer: boolean;
+  proxyCache: boolean;
+  lazyResolution: boolean;
+  env: Record<string, string>;
+  pythonPathExtra: string[];
+}
+
+export function resolveConfig(config: nodepyxConfig = {}): ResolvednodepyxConfig {
+  return {
+    pythonExecutable: config.pythonPath ?? 'python3',
+    pythonHome: config.pythonPath ?? '',
+    threadPoolSize: config.threadPool?.size ?? config.threadPoolSize ?? 4,
+    maxQueueSize: config.threadPool?.maxQueueSize ?? 1000,
+    idleTimeout: config.threadPool?.idleTimeout ?? 30000,
+    memoryLimit: config.memory?.limit ?? config.memoryLimit ?? '2GB',
+    gcThreshold: config.memory?.gcThreshold ?? '1GB',
+    leakDetection: config.memory?.leakDetection ?? false,
+    stubsDir: config.stubsDir ?? './.nodepyx/stubs',
+    logLevel: config.logLevel ?? 'warn',
+    callTimeout: config.callTimeout ?? 30000,
+    gil: {
+      releaseInterval: config.gil?.releaseInterval ?? 5000,
+      acquireTimeout: config.gil?.acquireTimeout ?? 10000,
+    },
+    profilingEnabled: config.profiling?.enabled ?? config.enableProfiling ?? false,
+    profilingFile: config.profiling?.outputFile,
+    profilingSamplingInterval: config.profiling?.samplingInterval ?? 1000,
+    sharedArrayBuffer: config.experimental?.sharedArrayBuffer ?? true,
+    proxyCache: config.experimental?.proxyCache ?? true,
+    lazyResolution: config.experimental?.lazyResolution ?? true,
+    env: config.env ?? {},
+    pythonPathExtra: config.pythonPath_extra ?? [],
+  };
+}
+

package/src/types/index.ts

@@ -0,0 +1,55 @@
+/**
+ * nodepyx — Types Index
+ * Re-exports all public type definitions.
+ */
+
+export type {
+  nodepyxConfig,
+  ResolvednodepyxConfig,
+  VirtualenvConfig,
+  CondaConfig,
+  GILConfig,
+  ThreadPoolConfig,
+  MemoryConfig,
+  ProfilingConfig,
+  LogLevel,
+} from './config';
+
+export { resolveConfig } from './config';
+
+export type {
+  PyObjectId,
+  PyTypeName,
+  PyTypeInfo,
+  PyParamInfo,
+  PyMemberInfo,
+  PyCallableInfo,
+  PyClassInfo,
+  PyModuleInspection,
+  SerializedFormat,
+  SerializedValue,
+  SerializedMetadata,
+  PyCallResult,
+  PyErrorInfo,
+  PyIteratorState,
+  PyIteratorNext,
+  DataFrameResult,
+  SeriesResult,
+  NumPyArrayResult,
+  AttributePath,
+  PyProxyInterface,
+} from './python';
+
+export type {
+  NativeAddon,
+  AddonInitOptions,
+  AddonImportResult,
+  AddonAttributeResult,
+  AddonCallOptions,
+  AddonIteratorResult,
+  AddonMemoryStats,
+  AddonProfilingReport,
+} from './addon';
+
+export { loadNativeAddon } from './addon';
+

package/src/types/python.ts

@@ -0,0 +1,309 @@
+/**
+ * nodepyx — Python Object Type Definitions
+ * Core types for representing Python objects in TypeScript.
+ */
+
+/**
+ * Unique identifier for a Python object in the CPython heap.
+ * Stored as a C-level pointer (opaque to JavaScript).
+ */
+export type PyObjectId = number & { readonly __brand: 'PyObjectId' };
+
+/**
+ * Python built-in type names.
+ */
+export type PyTypeName =
+  | 'int'
+  | 'float'
+  | 'complex'
+  | 'bool'
+  | 'str'
+  | 'bytes'
+  | 'bytearray'
+  | 'list'
+  | 'tuple'
+  | 'dict'
+  | 'set'
+  | 'frozenset'
+  | 'NoneType'
+  | 'function'
+  | 'method'
+  | 'builtin_function_or_method'
+  | 'module'
+  | 'type'
+  | 'classmethod'
+  | 'staticmethod'
+  | 'property'
+  | 'generator'
+  | 'coroutine'
+  | 'async_generator'
+  | 'iterator'
+  | 'DataFrame'
+  | 'Series'
+  | 'ndarray'
+  | 'Tensor'
+  | string;
+
+/**
+ * Metadata about a Python object's type.
+ */
+export interface PyTypeInfo {
+  typeName: PyTypeName;
+  moduleName?: string;
+  qualName?: string;
+  isCallable: boolean;
+  isIterable: boolean;
+  isAsyncIterable: boolean;
+  isAwaitable: boolean;
+  isClass: boolean;
+  isModule: boolean;
+  isNone: boolean;
+  isPrimitive: boolean;
+  isNumeric: boolean;
+  isSequence: boolean;
+  isMapping: boolean;
+}
+
+/**
+ * Parameter info from Python function introspection.
+ */
+export interface PyParamInfo {
+  name: string;
+  type: string;
+  optional: boolean;
+  hasDefault: boolean;
+  defaultValue?: unknown;
+  kind: 'positional_only' | 'positional_or_keyword' | 'var_positional' | 'keyword_only' | 'var_keyword';
+}
+
+/**
+ * Member/attribute info for a Python class or module.
+ */
+export interface PyMemberInfo {
+  name: string;
+  type: string;
+  isReadOnly: boolean;
+  docstring?: string;
+}
+
+/**
+ * Full introspection result for a Python callable.
+ */
+export interface PyCallableInfo {
+  name: string;
+  qualName: string;
+  docstring: string;
+  parameters: PyParamInfo[];
+  returnType: string;
+  isMethod: boolean;
+  isClassMethod: boolean;
+  isStaticMethod: boolean;
+  isCoroutine: boolean;
+  isGenerator: boolean;
+}
+
+/**
+ * Full introspection result for a Python class.
+ */
+export interface PyClassInfo {
+  name: string;
+  qualName: string;
+  docstring: string;
+  bases: string[];
+  members: PyMemberInfo[];
+  methods: PyCallableInfo[];
+  properties: PyMemberInfo[];
+  classMethods: PyCallableInfo[];
+  staticMethods: PyCallableInfo[];
+}
+
+/**
+ * Full introspection result for a Python module.
+ */
+export interface PyModuleInspection {
+  name: string;
+  file?: string;
+  docstring: string;
+  version?: string;
+  functions: PyCallableInfo[];
+  classes: PyClassInfo[];
+  constants: PyMemberInfo[];
+  submodules: string[];
+}
+
+/**
+ * Serialized wire format for Python ↔ JavaScript data transfer.
+ */
+export type SerializedFormat =
+  | 'json'
+  | 'msgpack'
+  | 'numpy_array'
+  | 'dataframe'
+  | 'series'
+  | 'pandas_dataframe'
+  | 'pandas_series'
+  | 'torch_tensor'
+  | 'python_ref'
+  | 'bytes'
+  | 'none'
+  | number;   // numeric codes from the C++ addon (0=json,1=msgpack,2=numpy,3=df,4=series,6=ref,7=bytes,8=none)
+
+export interface SerializedValue {
+  format: SerializedFormat;
+  data: Uint8Array | string | null | undefined;
+  metadata?: SerializedMetadata;
+}
+
+export interface SerializedMetadata {
+  /** For python_ref: the object ID */
+  objectId?: number;
+  /** For numpy_array: dtype, shape, strides */
+  dtype?: string;
+  shape?: number[];
+  strides?: number[];
+  order?: 'C' | 'F';
+  /** For numpy_array: item size in bytes (snake_case variant) */
+  itemsize?: number;
+  /** For pandas objects: column names, dtypes, index */
+  columns?: string[];
+  columnDtypes?: string[];
+  index?: unknown[];
+  indexName?: string;
+  /** For pandas: orient (split/records/index/columns/values) */
+  orient?: string;
+  /** For Series: series name */
+  name?: string;
+  /** For torch tensors */
+  device?: string;
+  requiresGrad?: boolean;
+  /** General */
+  length?: number;
+  size?: number;
+  itemSize?: number;
+}
+
+/**
+ * Result from a Python function call.
+ */
+export interface PyCallResult {
+  success: boolean;
+  value?: SerializedValue;
+  error?: PyErrorInfo;
+  objectId?: PyObjectId;
+  isObject?: boolean;
+}
+
+/**
+ * Python exception information.
+ */
+export interface PyErrorInfo {
+  /** Python exception class name, e.g. 'ValueError', 'FileNotFoundError' */
+  type: string;
+  /** Exception message */
+  message: string;
+  /** Full Python traceback */
+  traceback: string;
+  /** Exception module, e.g. 'builtins', 'pandas.errors' */
+  module?: string;
+  /** Chained exception */
+  cause?: PyErrorInfo;
+}
+
+/**
+ * Iterator state for Python iterators.
+ */
+export interface PyIteratorState {
+  iteratorId: number;
+  objectId: PyObjectId;
+  done: boolean;
+  position: number;
+}
+
+/**
+ * Result from iterator next() call.
+ */
+export interface PyIteratorNext {
+  done: boolean;
+  value?: SerializedValue;
+  error?: PyErrorInfo;
+}
+
+/**
+ * DataFrame representation after deserialization.
+ */
+export interface DataFrameResult {
+  columns: string[];
+  /** Row data as array of column-keyed objects */
+  data: Record<string, unknown>[];
+  /** Alias for data — array of records (row objects) */
+  records: Record<string, unknown>[];
+  index: unknown[];
+  dtypes: Record<string, string>;
+  shape: [number, number];
+}
+
+/**
+ * Series representation after deserialization.
+ */
+export interface SeriesResult {
+  name: string;
+  /** Series values */
+  data: unknown[];
+  /** Alias for data */
+  values: unknown[];
+  index: unknown[];
+  dtype: string;
+  length: number;
+}
+
+/**
+ * A typed array backed by numpy data.
+ */
+export type NumpyTypedArray =
+  | Float32Array
+  | Float64Array
+  | Int8Array
+  | Int16Array
+  | Int32Array
+  | BigInt64Array
+  | Uint8Array
+  | Uint16Array
+  | Uint32Array
+  | BigUint64Array;
+
+/**
+ * NumPy array representation after deserialization.
+ * Contains the typed array data plus metadata (dtype, shape, ndim).
+ */
+export interface NumPyArrayResult {
+  /** The underlying typed array */
+  data: NumpyTypedArray;
+  /** NumPy dtype string, e.g. 'float64' */
+  dtype: string;
+  /** Array shape */
+  shape: number[];
+  /** Number of dimensions */
+  ndim: number;
+}
+
+/**
+ * Attribute resolution path for lazy Proxy chains.
+ */
+export type AttributePath = string[];
+
+/**
+ * The core PyProxy interface — wraps any Python object.
+ * All properties return new PyProxy instances (lazy).
+ * Calling the proxy or awaiting it triggers the Python call.
+ */
+export interface PyProxyInterface {
+  readonly _pyObjectId: PyObjectId;
+  readonly _path: AttributePath;
+  readonly _isResolved: boolean;
+  then(
+    onfulfilled?: (value: unknown) => unknown,
+    onrejected?: (reason: PyErrorInfo) => unknown
+  ): Promise<unknown>;
+  [key: string]: unknown;
+}
+