tywrap 0.6.0 → 0.7.0

package/src/utils/codec.ts

@@ -111,6 +111,24 @@ export type DecodedValue =
 
 let arrowTableFrom: ((bytes: Uint8Array) => ArrowTable | Uint8Array) | undefined;
 
+// Why: lazy auto-registration (on first Arrow decode) imports apache-arrow at most
+// once per process. We cache the in-flight/settled attempt so concurrent decodes
+// share a single dynamic import, and a missing module is not re-probed on every call.
+let lazyRegistration: Promise<boolean> | undefined;
+
+// Why: the lazy decode path imports apache-arrow through the default Node loader, which
+// is hard to simulate-as-absent in a test env where the dependency IS installed. This
+// internal seam lets the unit suite exercise the "apache-arrow missing" clear-failure
+// branch deterministically. It is intentionally NOT re-exported from the package root
+// (see test/api_surface.test.ts) and is reset by clearArrowDecoder().
+let lazyArrowLoaderOverride: ArrowModuleLoader | undefined;
+
+/** @internal Test-only: override the loader used by lazy auto-registration. */
+export const _setLazyArrowLoaderForTesting = (loader: ArrowModuleLoader | undefined): void => {
+  lazyArrowLoaderOverride = loader;
+  lazyRegistration = undefined;
+};
+
 export function registerArrowDecoder(
   decoder: (bytes: Uint8Array) => ArrowTable | Uint8Array
 ): void {
@@ -119,6 +137,10 @@ export function registerArrowDecoder(
 
 export function clearArrowDecoder(): void {
   arrowTableFrom = undefined;
+  // Why: reset the cached import attempt so tests (and reload helpers) can exercise
+  // the auto-registration path again from a clean slate.
+  lazyRegistration = undefined;
+  lazyArrowLoaderOverride = undefined;
 }
 
 /**
@@ -186,6 +208,12 @@ export async function autoRegisterArrowDecoder(
   }
   try {
     const arrowModule = await loader();
+    // Another path may have registered a decoder while the import was in flight
+    // (e.g. an explicit registerArrowDecoder() during concurrent startup/reload).
+    // Don't clobber it — the explicit registration wins.
+    if (hasArrowDecoder()) {
+      return true;
+    }
     registerArrowDecoderFromModule(arrowModule as { tableFromIPC?: unknown });
     return true;
   } catch {
@@ -214,17 +242,46 @@ function fromBase64(b64: string): Uint8Array {
   throw new Error('Base64 decoding is not available in this runtime');
 }
 
+// Why: a single, actionable message for both decode paths so users always know the two
+// supported remedies — install the optional dependency, or opt into the lossy JSON fallback.
+const ARROW_MISSING_MESSAGE =
+  'Received an Arrow-encoded payload but no Arrow decoder is available. ' +
+  'Install the optional dependency with `npm install apache-arrow`, or set ' +
+  'TYWRAP_CODEC_FALLBACK=json on the Python side to receive JSON instead ' +
+  '(lossy for dtype/NA fidelity). tywrap never silently downgrades Arrow payloads.';
+
 function requireArrowDecoder(): (bytes: Uint8Array) => ArrowTable | Uint8Array {
   if (!arrowTableFrom) {
-    throw new Error(
-      'Arrow decoder not registered. Call registerArrowDecoder(...) or set TYWRAP_CODEC_FALLBACK=json in Python.'
-    );
+    throw new Error(ARROW_MISSING_MESSAGE);
+  }
+  return arrowTableFrom;
+}
+
+/**
+ * Ensure an Arrow decoder is registered, lazily importing apache-arrow on first use.
+ *
+ * Why: keep apache-arrow optional and zero-config. The first Arrow-encoded payload
+ * triggers a single best-effort dynamic import; if it succeeds the decoder is cached
+ * for the rest of the process. If apache-arrow is absent we throw a clear, actionable
+ * error rather than silently producing wrong data.
+ */
+async function ensureArrowDecoder(): Promise<(bytes: Uint8Array) => ArrowTable | Uint8Array> {
+  if (arrowTableFrom) {
+    return arrowTableFrom;
+  }
+  // Reuse a single import attempt across concurrent decodes.
+  lazyRegistration ??= autoRegisterArrowDecoder(
+    lazyArrowLoaderOverride ? { loader: lazyArrowLoaderOverride } : {}
+  );
+  await lazyRegistration;
+  if (!arrowTableFrom) {
+    throw new Error(ARROW_MISSING_MESSAGE);
   }
   return arrowTableFrom;
 }
 
 async function tryDecodeArrowTable(bytes: Uint8Array): Promise<ArrowTable | Uint8Array> {
-  const decoder = requireArrowDecoder();
+  const decoder = await ensureArrowDecoder();
   try {
     return decoder(bytes);
   } catch (err) {

package/src/utils/python.ts

@@ -44,30 +44,43 @@ export function getDefaultPythonPath(): string {
   return getPythonExecutableName();
 }
 
+/**
+ * Whether the configured pythonPath is the default interpreter (or unset),
+ * meaning a virtual environment lookup should take precedence.
+ */
+function usesDefaultPython(pythonPath: string | undefined): boolean {
+  return !pythonPath || pythonPath === 'python3' || pythonPath === 'python';
+}
+
+/**
+ * Resolve the Python executable inside a virtual environment, preferring the
+ * Node path module when available and falling back to cross-runtime pathUtils.
+ */
+async function resolveVenvPython(virtualEnv: string, cwd: string): Promise<string> {
+  const binDir = getVenvBinDir();
+  const exe = getVenvPythonExe();
+  const pathMod = await loadNodePathModule();
+
+  if (pathMod) {
+    const venvRoot = pathMod.resolve(cwd, virtualEnv);
+    return pathMod.join(venvRoot, binDir, exe);
+  }
+
+  const venvRoot = isAbsolutePath(virtualEnv)
+    ? pathUtils.join(virtualEnv)
+    : pathUtils.join(cwd, virtualEnv);
+  return pathUtils.join(venvRoot, binDir, exe);
+}
+
 export async function resolvePythonExecutable(options: PythonResolveOptions = {}): Promise<string> {
   const pythonPath = options.pythonPath?.trim();
   const virtualEnv = options.virtualEnv?.trim();
 
-  if (virtualEnv) {
-    const usesDefaultPython = !pythonPath || pythonPath === 'python3' || pythonPath === 'python';
-    if (usesDefaultPython) {
-      const cwd =
-        options.cwd ??
-        (typeof process !== 'undefined' && typeof process.cwd === 'function' ? process.cwd() : '.');
-      const binDir = getVenvBinDir();
-      const exe = getVenvPythonExe();
-      const pathMod = await loadNodePathModule();
-
-      if (pathMod) {
-        const venvRoot = pathMod.resolve(cwd, virtualEnv);
-        return pathMod.join(venvRoot, binDir, exe);
-      }
-
-      const venvRoot = isAbsolutePath(virtualEnv)
-        ? pathUtils.join(virtualEnv)
-        : pathUtils.join(cwd, virtualEnv);
-      return pathUtils.join(venvRoot, binDir, exe);
-    }
+  if (virtualEnv && usesDefaultPython(pythonPath)) {
+    const cwd =
+      options.cwd ??
+      (typeof process !== 'undefined' && typeof process.cwd === 'function' ? process.cwd() : '.');
+    return resolveVenvPython(virtualEnv, cwd);
   }
 
   if (pythonPath) {

package/src/utils/runtime.ts

@@ -229,26 +229,37 @@ async function loadPathModule(): Promise<PathModule | null> {
   return null;
 }
 
+/**
+ * Apply a single path segment to the accumulated normalized segments,
+ * resolving '..' and dropping '.'/empty segments in place.
+ */
+function applyPathSegment(normalized: string[], segment: string, isAbsolute: boolean): void {
+  if (segment === '.' || segment === '') {
+    return; // Skip current directory and empty segments
+  }
+
+  if (segment !== '..') {
+    normalized.push(segment);
+    return;
+  }
+
+  // '..' segment: go up one directory when possible.
+  if (normalized.length > 0 && normalized[normalized.length - 1] !== '..') {
+    normalized.pop();
+  } else if (!isAbsolute) {
+    normalized.push(segment); // Keep '..' if not absolute and at root
+  }
+}
+
 /**
  * Normalize path by stripping '.' and resolving '..' components
  */
 function normalizePath(path: string): string {
   const isAbsolute = path.startsWith('/');
-  const segments = path.split('/');
   const normalized: string[] = [];
 
-  for (const segment of segments) {
-    if (segment === '.' || segment === '') {
-      continue; // Skip current directory and empty segments
-    } else if (segment === '..') {
-      if (normalized.length > 0 && normalized[normalized.length - 1] !== '..') {
-        normalized.pop(); // Go up one directory
-      } else if (!isAbsolute) {
-        normalized.push(segment); // Keep '..' if not absolute and at root
-      }
-    } else {
-      normalized.push(segment);
-    }
+  for (const segment of path.split('/')) {
+    applyPathSegment(normalized, segment, isAbsolute);
   }
 
   const result = normalized.join('/');

package/src/version.ts

@@ -9,4 +9,4 @@
  * Regenerate with: node scripts/generate-version.mjs
  */
 
-export const VERSION: string = "0.6.0";
+export const VERSION: string = "0.7.0";