@inferencesh/app 0.1.4 → 0.1.6

package/dist/file.d.ts

@@ -22,22 +22,60 @@ export interface FileData {
  * A file in the inference.sh ecosystem.
  *
  * Accepts a URL, local path, or options object.
- * URLs are downloaded and cached locally on construction (via `await File.from()`).
+ * URLs are downloaded lazily when `getPath()` is called.
  * Local paths are resolved to absolute paths.
  *
+ * For API wrapper apps that only need to forward the URL, use `uri` directly
+ * without calling `getPath()` to avoid unnecessary downloads.
+ *
  * In JSON output, File serializes to `{ path, uri, content_type, size, filename }`
  * — the engine uploads local `path` files to CDN and replaces with `uri`.
  */
 export declare class File {
     uri?: string;
-    path?: string;
     contentType?: string;
     size?: number;
     filename?: string;
+    private _path?;
+    private _resolved;
+    private _downloading?;
     private constructor();
+    /**
+     * Get the local file path. Downloads the file lazily if needed.
+     * For sync access after download, use the `path` getter.
+     */
+    getPath(): Promise<string>;
+    /**
+     * Sync access to path. Returns undefined if not yet downloaded.
+     * Use `getPath()` for lazy downloading.
+     */
+    get path(): string | undefined;
+    /**
+     * Check if the file has been downloaded/resolved.
+     */
+    get isResolved(): boolean;
+    private _resolve;
+    /**
+     * Create a lazy File from a URL or path string.
+     * Does NOT download immediately — download happens when `getPath()` is called.
+     *
+     * Note: This is safe in JS because `getPath()` is async. The Python SDK had to
+     * revert to eager download because `.path` is a sync property that blocks the
+     * event loop when called from async code (e.g. Playwright + httpx apps).
+     *
+     * @example
+     * ```js
+     * const file = File.lazy("https://example.com/image.jpg");
+     * console.log(file.uri);  // Available immediately
+     * const path = await file.getPath();  // Downloads here
+     * ```
+     */
+    static lazy(input: string): File;
     /**
      * Create a File from a URL, local path, or options object.
-     * URLs are downloaded and cached automatically.
+     * URLs are downloaded and cached automatically (eager loading).
+     *
+     * For lazy loading, use `File.lazy()` instead.
      *
      * @example
      * ```js
@@ -58,8 +96,14 @@ export declare class File {
     static fromPath(localPath: string): File;
     /**
      * Check if the file exists on disk.
+     * Note: This checks the current state without triggering download.
+     * Use `getPath()` first if you need to ensure the file is downloaded.
      */
     exists(): boolean;
+    /**
+     * Check if we have a local path (without triggering download).
+     */
+    isLocal(): boolean;
     /**
      * Re-read metadata (contentType, size, filename) from disk.
      */
@@ -67,6 +111,7 @@ export declare class File {
     /**
      * Serialize to a plain object for JSON output.
      * The engine reads `path` fields and uploads them to CDN.
+     * Note: Uses internal _path to avoid triggering download during serialization.
      */
     toJSON(): FileData;
     static getCacheDir(): string;

package/dist/file.js

@@ -9,28 +9,120 @@ import { URL } from "node:url";
  * A file in the inference.sh ecosystem.
  *
  * Accepts a URL, local path, or options object.
- * URLs are downloaded and cached locally on construction (via `await File.from()`).
+ * URLs are downloaded lazily when `getPath()` is called.
  * Local paths are resolved to absolute paths.
  *
+ * For API wrapper apps that only need to forward the URL, use `uri` directly
+ * without calling `getPath()` to avoid unnecessary downloads.
+ *
  * In JSON output, File serializes to `{ path, uri, content_type, size, filename }`
  * — the engine uploads local `path` files to CDN and replaces with `uri`.
  */
 export class File {
     uri;
-    path;
     contentType;
     size;
     filename;
+    _path;
+    _resolved = false;
+    _downloading;
     constructor(options) {
         this.uri = options.uri;
-        this.path = options.path;
+        this._path = options.path;
         this.contentType = options.contentType;
         this.size = options.size;
         this.filename = options.filename;
     }
+    /**
+     * Get the local file path. Downloads the file lazily if needed.
+     * For sync access after download, use the `path` getter.
+     */
+    async getPath() {
+        if (this._resolved && this._path) {
+            return this._path;
+        }
+        // Avoid concurrent downloads
+        if (this._downloading) {
+            return this._downloading;
+        }
+        this._downloading = this._resolve();
+        try {
+            const path = await this._downloading;
+            return path;
+        }
+        finally {
+            this._downloading = undefined;
+        }
+    }
+    /**
+     * Sync access to path. Returns undefined if not yet downloaded.
+     * Use `getPath()` for lazy downloading.
+     */
+    get path() {
+        return this._path;
+    }
+    /**
+     * Check if the file has been downloaded/resolved.
+     */
+    get isResolved() {
+        return this._resolved;
+    }
+    async _resolve() {
+        if (this._resolved && this._path) {
+            return this._path;
+        }
+        if (this.uri) {
+            if (isDataUri(this.uri)) {
+                this._decodeDataUri(this.uri);
+            }
+            else if (isUrl(this.uri)) {
+                await this._downloadUrl(this.uri);
+            }
+            else {
+                // Treat as local path
+                this._path = resolve(this.uri);
+            }
+        }
+        if (this._path) {
+            this._path = resolve(this._path);
+            this._populateMetadata();
+        }
+        this._resolved = true;
+        if (!this._path) {
+            throw new Error("Failed to resolve file path");
+        }
+        return this._path;
+    }
+    /**
+     * Create a lazy File from a URL or path string.
+     * Does NOT download immediately — download happens when `getPath()` is called.
+     *
+     * Note: This is safe in JS because `getPath()` is async. The Python SDK had to
+     * revert to eager download because `.path` is a sync property that blocks the
+     * event loop when called from async code (e.g. Playwright + httpx apps).
+     *
+     * @example
+     * ```js
+     * const file = File.lazy("https://example.com/image.jpg");
+     * console.log(file.uri);  // Available immediately
+     * const path = await file.getPath();  // Downloads here
+     * ```
+     */
+    static lazy(input) {
+        const file = new File({ uri: input });
+        // If it's a local path (not URL or data URI), resolve immediately
+        if (!isUrl(input) && !isDataUri(input)) {
+            file._path = resolve(input);
+            file._resolved = true;
+            file._populateMetadata();
+        }
+        return file;
+    }
     /**
      * Create a File from a URL, local path, or options object.
-     * URLs are downloaded and cached automatically.
+     * URLs are downloaded and cached automatically (eager loading).
+     *
+     * For lazy loading, use `File.lazy()` instead.
      *
      * @example
      * ```js
@@ -48,7 +140,7 @@ export class File {
         if (input instanceof File) {
             return new File({
                 uri: input.uri,
-                path: input.path,
+                path: input._path,
                 contentType: input.contentType,
                 size: input.size,
                 filename: input.filename,
@@ -72,26 +164,8 @@ export class File {
             throw new Error("Either 'uri' or 'path' must be provided");
         }
         const file = new File(options);
-        // Resolve URI
-        if (file.uri) {
-            if (isDataUri(file.uri)) {
-                file._decodeDataUri(file.uri);
-            }
-            else if (isUrl(file.uri)) {
-                await file._downloadUrl(file.uri);
-            }
-            else {
-                // Treat as local path
-                file.path = resolve(file.uri);
-            }
-        }
-        if (file.path) {
-            file.path = resolve(file.path);
-            file._populateMetadata();
-        }
-        else {
-            throw new Error("Either 'uri' or 'path' must be provided and be valid");
-        }
+        // Eagerly resolve
+        await file.getPath();
         return file;
     }
     /**
@@ -100,14 +174,23 @@ export class File {
     static fromPath(localPath) {
         const absPath = resolve(localPath);
         const file = new File({ path: absPath });
+        file._resolved = true;
         file._populateMetadata();
         return file;
     }
     /**
      * Check if the file exists on disk.
+     * Note: This checks the current state without triggering download.
+     * Use `getPath()` first if you need to ensure the file is downloaded.
      */
     exists() {
-        return this.path != null && existsSync(this.path);
+        return this._path != null && existsSync(this._path);
+    }
+    /**
+     * Check if we have a local path (without triggering download).
+     */
+    isLocal() {
+        return this._path != null;
     }
     /**
      * Re-read metadata (contentType, size, filename) from disk.
@@ -118,13 +201,14 @@ export class File {
     /**
      * Serialize to a plain object for JSON output.
      * The engine reads `path` fields and uploads them to CDN.
+     * Note: Uses internal _path to avoid triggering download during serialization.
      */
     toJSON() {
         const result = {};
         if (this.uri != null)
             result.uri = this.uri;
-        if (this.path != null)
-            result.path = this.path;
+        if (this._path != null)
+            result.path = this._path;
         if (this.contentType != null)
             result.content_type = this.contentType;
         if (this.size != null)
@@ -161,7 +245,8 @@ export class File {
         if (existsSync(cacheDir)) {
             const files = require("node:fs").readdirSync(cacheDir);
             if (files.length > 0) {
-                this.path = join(cacheDir, files[0]);
+                this._path = join(cacheDir, files[0]);
+                this._populateMetadata();
                 return;
             }
         }
@@ -175,20 +260,23 @@ export class File {
         const filename = `file${ext}`;
         const cachePath = join(cacheDir, filename);
         writeFileSync(cachePath, parsed.data);
-        this.path = cachePath;
+        this._path = cachePath;
+        this._populateMetadata();
     }
     // --- Download ---
     async _downloadUrl(url) {
         const cachePath = this._getCachePath(url);
         if (existsSync(cachePath)) {
-            this.path = cachePath;
+            this._path = cachePath;
+            this._populateMetadata();
             return;
         }
         const tmpPath = cachePath + ".tmp";
         try {
             await downloadToFile(url, tmpPath);
             renameSync(tmpPath, cachePath);
-            this.path = cachePath;
+            this._path = cachePath;
+            this._populateMetadata();
         }
         catch (err) {
             try {
@@ -200,19 +288,19 @@ export class File {
     }
     // --- Metadata ---
     _populateMetadata() {
-        if (!this.path || !existsSync(this.path))
+        if (!this._path || !existsSync(this._path))
             return;
         if (!this.contentType) {
-            this.contentType = guessContentType(this.path);
+            this.contentType = guessContentType(this._path);
         }
         if (this.size == null) {
             try {
-                this.size = statSync(this.path).size;
+                this.size = statSync(this._path).size;
             }
             catch { /* ignore */ }
         }
         if (!this.filename) {
-            this.filename = basename(this.path);
+            this.filename = basename(this._path);
         }
     }
 }

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { File } from "./file.js";
 export type { FileOptions, FileData } from "./file.js";
+export { createFileSchema, isFileSchema, FILE_SCHEMA_MARKER } from "./schema.js";
 export { StorageDir, ensureDir } from "./storage.js";
 export type { StorageDirValue } from "./storage.js";
 export { download } from "./download.js";

package/dist/index.js

@@ -1,5 +1,7 @@
 // File handling
 export { File } from "./file.js";
+// Zod schema utilities
+export { createFileSchema, isFileSchema, FILE_SCHEMA_MARKER } from "./schema.js";
 // Storage directories
 export { StorageDir, ensureDir } from "./storage.js";
 // Download utility

package/dist/schema.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Zod schema utilities for inference.sh apps.
+ *
+ * Provides a `fileSchema` that:
+ * - Accepts URL strings as input
+ * - Transforms to lazy File objects (no download until getPath() called)
+ * - Generates JSON Schema with format: "file"
+ */
+/**
+ * Symbol to mark a schema as a file schema.
+ * The kernel's zodToJsonSchema will detect this and output format: "file".
+ */
+export declare const FILE_SCHEMA_MARKER: unique symbol;
+/**
+ * Create a file schema using the app's Zod instance.
+ *
+ * @example
+ * ```js
+ * import { z } from "zod";
+ * import { createFileSchema } from "@inferencesh/app";
+ *
+ * const fileSchema = createFileSchema(z);
+ *
+ * const InputSchema = z.object({
+ *   image: fileSchema.describe("Input image"),
+ * });
+ * ```
+ */
+export declare function createFileSchema(z: any): any;
+/**
+ * Check if a Zod schema is a file schema (created by createFileSchema).
+ */
+export declare function isFileSchema(schema: any): boolean;

package/dist/schema.js

@@ -0,0 +1,52 @@
+/**
+ * Zod schema utilities for inference.sh apps.
+ *
+ * Provides a `fileSchema` that:
+ * - Accepts URL strings as input
+ * - Transforms to lazy File objects (no download until getPath() called)
+ * - Generates JSON Schema with format: "file"
+ */
+import { File } from "./file.js";
+// We don't import zod directly to avoid version conflicts.
+// Instead, apps provide their own zod and we work with the schema structure.
+/**
+ * Symbol to mark a schema as a file schema.
+ * The kernel's zodToJsonSchema will detect this and output format: "file".
+ */
+export const FILE_SCHEMA_MARKER = Symbol.for("inferencesh.fileSchema");
+/**
+ * Create a file schema using the app's Zod instance.
+ *
+ * @example
+ * ```js
+ * import { z } from "zod";
+ * import { createFileSchema } from "@inferencesh/app";
+ *
+ * const fileSchema = createFileSchema(z);
+ *
+ * const InputSchema = z.object({
+ *   image: fileSchema.describe("Input image"),
+ * });
+ * ```
+ */
+export function createFileSchema(z) {
+    const schema = z.string().transform((uri) => File.lazy(uri));
+    // Mark as file schema for JSON schema generation
+    schema._def[FILE_SCHEMA_MARKER] = true;
+    return schema;
+}
+/**
+ * Check if a Zod schema is a file schema (created by createFileSchema).
+ */
+export function isFileSchema(schema) {
+    if (!schema || typeof schema !== "object")
+        return false;
+    // Check for our marker
+    if (schema._def && schema._def[FILE_SCHEMA_MARKER])
+        return true;
+    // Check inner type for transforms/effects
+    if (schema._def?.typeName === "ZodEffects" && schema._def.schema) {
+        return isFileSchema(schema._def.schema);
+    }
+    return false;
+}

package/dist/types.js

@@ -1,4 +1,4 @@
-// Code generated by tygo. DO NOT EDIT.
+// Code generated by gotypegen. DO NOT EDIT.
 export const MetaItemTypeText = "text";
 export const MetaItemTypeImage = "image";
 export const MetaItemTypeVideo = "video";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inferencesh/app",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "App framework for building inference.sh apps — File handling, output metadata, storage utilities",
   "type": "module",
   "main": "dist/index.js",
@@ -42,7 +42,8 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "rimraf": "^6.0.1",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "zod": "^4.3.6"
   },
   "files": [
     "dist",