Generate TypeScript definitions from source

Author: aron

Diff for: index.d.ts

@@ -1,20 +1,21 @@
-const Replicate = require("./lib/replicate");
+const ReplicateClass = require("./lib/replicate");
 const ApiError = require("./lib/error");
+require("./lib/types");
 
 /**
  * Placeholder class used to warn of deprecated constructor.
  * @deprecated use exported Replicate class instead
  */
-class DeprecatedReplicate extends Replicate {
+class DeprecatedReplicate extends ReplicateClass {
   /** @deprecated Use `import { Replicate } from "replicate";` instead */
   // biome-ignore lint/complexity/noUselessConstructor: exists for the tsdoc comment
   constructor(...args) {
     super(...args);
   }
 }
 
-const named = { ApiError, Replicate };
-const singleton = new Replicate();
+const named = { ApiError, Replicate: ReplicateClass };
+const singleton = new ReplicateClass();
 
 /**
  * Default instance of the Replicate class that gets the access token
@@ -48,7 +49,7 @@ const singleton = new Replicate();
  * const client = new Replicate({...});
  * ```
  *
- * @type { Replicate & typeof DeprecatedReplicate & {ApiError: ApiError, Replicate: Replicate} }
+ * @type { Replicate & typeof DeprecatedReplicate & {Replicate: typeof ReplicateClass} }
  */
 const replicate = new Proxy(DeprecatedReplicate, {
   get(target, prop, receiver) {
@@ -70,3 +71,26 @@ const replicate = new Proxy(DeprecatedReplicate, {
 });
 
 module.exports = replicate;
+
+// - Type Definitions
+
+/** 
+ * @typedef {import("./lib/replicate")} Replicate
+ * @typedef {import("./lib/error")} ApiError
+ * @typedef {typeof import("./lib/types").Collection} Collection
+ * @typedef {typeof import("./lib/types").ModelVersion} ModelVersion
+ * @typedef {typeof import("./lib/types").Hardware} Hardware
+ * @typedef {typeof import("./lib/types").Model} Model
+ * @typedef {typeof import("./lib/types").Prediction} Prediction
+ * @typedef {typeof import("./lib/types").Training} Training
+ * @typedef {typeof import("./lib/types").ServerSentEvent} ServerSentEvent
+ * @typedef {typeof import("./lib/types").Status} Status
+ * @typedef {typeof import("./lib/types").Visibility} Visibility
+ * @typedef {typeof import("./lib/types").WebhookEventType} WebhookEventType
+ */
+
+/**
+ * @template T
+ * @typedef {typeof import("./lib/types").Page} Page
+ */
+

Diff for: index.js

@@ -1,5 +1,5 @@
 import { expect, jest, test } from "@jest/globals";
-import replicate, { ApiError, Model, Prediction, Replicate } from "replicate";
+import replicate, { ApiError, Model, Prediction, Replicate } from "./";
 import nock from "nock";
 import fetch from "cross-fetch";
 import assert from "node:assert";
@@ -216,6 +216,7 @@ function testInstance(createClient: (opts?: object) => Replicate) {
         });
       const client = createClient();
       const prediction = await client.predictions.create({
+        model: "foo",
         version:
           "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa",
         input: {
@@ -237,6 +238,7 @@ function testInstance(createClient: (opts?: object) => Replicate) {
 
       const client = createClient();
       await client.predictions.create({
+        model: "foo",
         version:
           "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa",
         input: {
@@ -250,6 +252,7 @@ function testInstance(createClient: (opts?: object) => Replicate) {
       await expect(async () => {
       const client = createClient();
         await client.predictions.create({
+          model: "foo",
           version:
             "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa",
           input: {
@@ -275,6 +278,7 @@ function testInstance(createClient: (opts?: object) => Replicate) {
 
       const client = createClient();
         await client.predictions.create({
+          model: "foo",
           version:
             "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa",
           input: {
@@ -303,6 +307,7 @@ function testInstance(createClient: (opts?: object) => Replicate) {
         });
       const client = createClient();
       const prediction = await client.predictions.create({
+        model: "foo",
         version:
           "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa",
         input: {
@@ -324,6 +329,7 @@ function testInstance(createClient: (opts?: object) => Replicate) {
       const client = createClient();
       await expect(
         client.predictions.create({
+          model: "foo",
           version:
             "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa",
           input: {
@@ -885,7 +891,6 @@ function testInstance(createClient: (opts?: object) => Replicate) {
     });
 
     test("Calls the correct API routes for a model", async () => {
-      const firstPollingRequest = true;
 
       nock(BASE_URL)
         .post("/models/replicate/hello-world/predictions")
@@ -968,12 +973,10 @@ function testInstance(createClient: (opts?: object) => Replicate) {
       const client = createClient();
       const options = { input: { text: "Hello, world!" } };
 
-      // @ts-expect-error
       await expect(client.run("owner:abc123", options)).rejects.toThrow();
 
       await expect(client.run("/model:abc123", options)).rejects.toThrow();
 
-      // @ts-expect-error
       await expect(client.run(":abc123", options)).rejects.toThrow();
     });
 

Diff for: index.test.ts

@@ -0,0 +1,61 @@
+import { ApiError, Hardware, Model, ModelVersion, Page, Prediction, Status, Training, Visibility, WebhookEventType } from "replicate";
+
+// NOTE: We export the constants to avoid unused varaible issues.
+
+export const collection: Collection = { name: "", slug: "", description: "", models: [] };
+export const status: Status = "starting";
+export const visibility: Visibility = "public";
+export const webhookType: WebhookEventType = "start";
+export const err: ApiError = Object.assign(new Error(), {request: new Request("file://"), response: new Response()});
+export const hardware: Hardware = { sku: "", name: "" };
+export const model: Model = {
+    url: "",
+    owner: "",
+    name: "",
+    description: "",
+    visibility: "public",
+    github_url: "",
+    paper_url: "",
+    license_url: "",
+    run_count: 10,
+    cover_image_url: "",
+    default_example: undefined,
+    latest_version: undefined,
+};
+export const version: ModelVersion = {
+    id: "",
+    created_at: "",
+    cog_version: "",
+    openapi_schema: "",
+};
+export const prediction: Prediction = {
+    id: "",
+    status: "starting",
+    model: "",
+    version: "",
+    input: {},
+    output: {},
+    source: "api",
+    error: undefined,
+    logs: "",
+    metrics: {
+        predict_time: 100,
+    },
+    webhook: "",
+    webhook_events_filter: [],
+    created_at: "",
+    started_at: "",
+    completed_at: "",
+    urls: {
+        get: "",
+        cancel: "",
+        stream: "",
+    },
+};
+export const training: Training = prediction;
+
+export const page: Page<ModelVersion> = {
+    previous: "",
+    next: "",
+    results: [version],
+};

Diff for: integration/typescript/types.test.ts

@@ -2,7 +2,7 @@
  * Fetch a model collection
  *
  * @param {string} collection_slug - Required. The slug of the collection. See http://replicate.com/collections
- * @returns {Promise<object>} - Resolves with the collection data
+ * @returns {Promise<Collection>} - Resolves with the collection data
  */
 async function getCollection(collection_slug) {
   const response = await this.request(`/collections/${collection_slug}`, {
@@ -15,7 +15,7 @@ async function getCollection(collection_slug) {
 /**
  * Fetch a list of model collections
  *
- * @returns {Promise<object>} - Resolves with the collections data
+ * @returns {Promise<Page<Collection>>} - Resolves with the collections data
  */
 async function listCollections() {
   const response = await this.request("/collections", {

Diff for: lib/collections.js

@@ -7,8 +7,8 @@
  * @param {object} options.input - Required. An object with the model inputs
  * @param {boolean} [options.stream] - Whether to stream the prediction output. Defaults to false
  * @param {string} [options.webhook] - An HTTPS URL for receiving a webhook when the prediction has new output
- * @param {string[]} [options.webhook_events_filter] - You can change which events trigger webhook requests by specifying webhook events (`start`|`output`|`logs`|`completed`)
- * @returns {Promise<object>} Resolves with the created prediction data
+ * @param {WebhookEventType[]} [options.webhook_events_filter] - You can change which events trigger webhook requests by specifying webhook events (`start`|`output`|`logs`|`completed`)
+ * @returns {Promise<Prediction>} Resolves with the created prediction data
  */
 async function createPrediction(deployment_owner, deployment_name, options) {
   const { stream, ...data } = options;

Diff for: lib/deployments.js

@@ -1,7 +1,7 @@
 /**
  * List hardware
  *
- * @returns {Promise<object[]>} Resolves with the array of hardware
+ * @returns {Promise<Hardware[]>} Resolves with the array of hardware
  */
 async function listHardware() {
   const response = await this.request("/hardware", {

Diff for: lib/hardware.js

@@ -3,7 +3,7 @@
  *
  * @param {string} model_owner - Required. The name of the user or organization that owns the model
  * @param {string} model_name - Required. The name of the model
- * @returns {Promise<object>} Resolves with the model data
+ * @returns {Promise<Model>} Resolves with the model data
  */
 async function getModel(model_owner, model_name) {
   const response = await this.request(`/models/${model_owner}/${model_name}`, {
@@ -18,7 +18,7 @@ async function getModel(model_owner, model_name) {
  *
  * @param {string} model_owner - Required. The name of the user or organization that owns the model
  * @param {string} model_name - Required. The name of the model
- * @returns {Promise<object>} Resolves with the list of model versions
+ * @returns {Promise<Page<ModelVersion>>} Resolves with the list of model versions
  */
 async function listModelVersions(model_owner, model_name) {
   const response = await this.request(
@@ -37,7 +37,7 @@ async function listModelVersions(model_owner, model_name) {
  * @param {string} model_owner - Required. The name of the user or organization that owns the model
  * @param {string} model_name - Required. The name of the model
  * @param {string} version_id - Required. The model version
- * @returns {Promise<object>} Resolves with the model version data
+ * @returns {Promise<ModelVersion>} Resolves with the model version data
  */
 async function getModelVersion(model_owner, model_name, version_id) {
   const response = await this.request(
@@ -53,7 +53,7 @@ async function getModelVersion(model_owner, model_name, version_id) {
 /**
  * List all public models
  *
- * @returns {Promise<object>} Resolves with the model version data
+ * @returns {Promise<Page<Model>>} Resolves with the model version data
  */
 async function listModels() {
   const response = await this.request("/models", {
@@ -72,11 +72,11 @@ async function listModels() {
  * @param {("public"|"private")} options.visibility - Required. Whether the model should be public or private. A public model can be viewed and run by anyone, whereas a private model can be viewed and run only by the user or organization members that own the model.
  * @param {string} options.hardware - Required. The SKU for the hardware used to run the model. Possible values can be found by calling `Replicate.hardware.list()`.
  * @param {string} options.description - A description of the model.
- * @param {string} options.github_url - A URL for the model's source code on GitHub.
- * @param {string} options.paper_url - A URL for the model's paper.
- * @param {string} options.license_url - A URL for the model's license.
- * @param {string} options.cover_image_url - A URL for the model's cover image. This should be an image file.
- * @returns {Promise<object>} Resolves with the model version data
+ * @param {string=} options.github_url - A URL for the model's source code on GitHub.
+ * @param {string=} options.paper_url - A URL for the model's paper.
+ * @param {string=} options.license_url - A URL for the model's license.
+ * @param {string=} options.cover_image_url - A URL for the model's cover image. This should be an image file.
+ * @returns {Promise<Model>} Resolves with the model version data
  */
 async function createModel(model_owner, model_name, options) {
   const data = { owner: model_owner, name: model_name, ...options };

Diff for: lib/models.js

@@ -2,13 +2,13 @@
  * Create a new prediction
  *
  * @param {object} options
- * @param {string} options.model - The model.
- * @param {string} options.version - The model version.
+ * @param {string=} options.model - The model (for official models)
+ * @param {string=} options.version - The model version.
  * @param {object} options.input - Required. An object with the model inputs
  * @param {string} [options.webhook] - An HTTPS URL for receiving a webhook when the prediction has new output
  * @param {string[]} [options.webhook_events_filter] - You can change which events trigger webhook requests by specifying webhook events (`start`|`output`|`logs`|`completed`)
  * @param {boolean} [options.stream] - Whether to stream the prediction output. Defaults to false
- * @returns {Promise<object>} Resolves with the created prediction
+ * @returns {Promise<Prediction>} Resolves with the created prediction
  */
 async function createPrediction(options) {
   const { model, version, stream, ...data } = options;
@@ -43,8 +43,8 @@ async function createPrediction(options) {
 /**
  * Fetch a prediction by ID
  *
- * @param {number} prediction_id - Required. The prediction ID
- * @returns {Promise<object>} Resolves with the prediction data
+ * @param {string} prediction_id - Required. The prediction ID
+ * @returns {Promise<Prediction>} Resolves with the prediction data
  */
 async function getPrediction(prediction_id) {
   const response = await this.request(`/predictions/${prediction_id}`, {
@@ -58,7 +58,7 @@ async function getPrediction(prediction_id) {
  * Cancel a prediction by ID
  *
  * @param {string} prediction_id - Required. The training ID
- * @returns {Promise<object>} Resolves with the data for the training
+ * @returns {Promise<Prediction>} Resolves with the data for the training
  */
 async function cancelPrediction(prediction_id) {
   const response = await this.request(`/predictions/${prediction_id}/cancel`, {
@@ -71,7 +71,7 @@ async function cancelPrediction(prediction_id) {
 /**
  * List all predictions
  *
- * @returns {Promise<object>} - Resolves with a page of predictions
+ * @returns {Promise<Page<Prediction>>} - Resolves with a page of predictions
  */
 async function listPredictions() {
   const response = await this.request("/predictions", {

Diff for: lib/predictions.js

@@ -49,9 +49,9 @@ module.exports = class Replicate {
    * const input = {text: 'Hello, world!'}
    * const output = await replicate.run(model, { input });
    *
-   * @param {object} options - Configuration options for the client
-   * @param {string} options.auth - API access token. Defaults to the `REPLICATE_API_TOKEN` environment variable.
-   * @param {string} options.userAgent - Identifier of your app
+   * @param {Object={}} options - Configuration options for the client
+   * @param {string} [options.auth] - API access token. Defaults to the `REPLICATE_API_TOKEN` environment variable.
+   * @param {string} [options.userAgent] - Identifier of your app
    * @param {string} [options.baseUrl] - Defaults to https://api.replicate.com/v1
    * @param {Function} [options.fetch] - Fetch function to use. Defaults to `globalThis.fetch`
    */

Diff for: lib/replicate.js

@@ -9,7 +9,7 @@
  * @param {object} options.input - Required. An object with the model inputs
  * @param {string} [options.webhook] - An HTTPS URL for receiving a webhook when the training updates
  * @param {string[]} [options.webhook_events_filter] - You can change which events trigger webhook requests by specifying webhook events (`start`|`output`|`logs`|`completed`)
- * @returns {Promise<object>} Resolves with the data for the created training
+ * @returns {Promise<Training>} Resolves with the data for the created training
  */
 async function createTraining(model_owner, model_name, version_id, options) {
   const { ...data } = options;
@@ -38,7 +38,7 @@ async function createTraining(model_owner, model_name, version_id, options) {
  * Fetch a training by ID
  *
  * @param {string} training_id - Required. The training ID
- * @returns {Promise<object>} Resolves with the data for the training
+ * @returns {Promise<Training>} Resolves with the data for the training
  */
 async function getTraining(training_id) {
   const response = await this.request(`/trainings/${training_id}`, {
@@ -52,7 +52,7 @@ async function getTraining(training_id) {
  * Cancel a training by ID
  *
  * @param {string} training_id - Required. The training ID
- * @returns {Promise<object>} Resolves with the data for the training
+ * @returns {Promise<Training>} Resolves with the data for the training
  */
 async function cancelTraining(training_id) {
   const response = await this.request(`/trainings/${training_id}/cancel`, {
@@ -65,7 +65,7 @@ async function cancelTraining(training_id) {
 /**
  * List all trainings
  *
- * @returns {Promise<object>} - Resolves with a page of trainings
+ * @returns {Promise<Page<Training>>} - Resolves with a page of trainings
  */
 async function listTrainings() {
   const response = await this.request("/trainings", {

Diff for: lib/trainings.js

@@ -0,0 +1,71 @@
+/** 
+ * @typedef {"starting" | "processing" | "succeeded" | "failed" | "canceled"} Status
+ * @typedef {"public" | "private"} Visibility
+ * @typedef {"start" | "output" | "logs" | "completed"} WebhookEventType 
+ *
+ * @typedef {import('./lib/error')} ApiError
+ *
+ * @typedef {Object} Collection
+ * @property {string} name
+ * @property {string} slug
+ * @property {string} description
+ * @property {Model[]=} models
+ *
+ * @typedef {Object} Hardware
+ * @property {string} sku
+ * @property {string} name
+ *
+ * @typedef {Object} Model
+ * @property {string} url
+ * @property {string} owner
+ * @property {string} name
+ * @property {string=} description
+ * @property {Visibility} visibility
+ * @property {string=} github_url
+ * @property {string=} paper_url
+ * @property {string=} license_url
+ * @property {number} run_count
+ * @property {string=} cover_image_url
+ * @property {Prediction=} default_example
+ * @property {ModelVersion=} latest_version
+ *
+ * @typedef {Object} ModelVersion
+ * @property {string} id
+ * @property {string} created_at
+ * @property {string} cog_version
+ * @property {string} openapi_schema
+ *
+ * @typedef {Object} Prediction
+ * @property {string} id
+ * @property {Status} status
+ * @property {string=} model
+ * @property {string} version
+ * @property {object} input
+ * @property {unknown=} output
+ * @property {"api" | "web"} source
+ * @property {unknown=} error
+ * @property {string=} logs
+ * @property {{predict_time?: number}=} metrics
+ * @property {string=} webhook
+ * @property {WebhookEventType[]=} webhook_events_filter
+ * @property {string} created_at
+ * @property {string=} started_at
+ * @property {string=} completed_at
+ * @property {{get: string; cancel: string; stream?: string}} urls
+ *
+ * @typedef {Prediction} Training
+ *
+ * @property {Object} ServerSentEvent
+ * @property {string} event
+ * @property {string} data
+ * @property {string=} id
+ * @property {number=} retry
+ */
+
+/**
+ * @template T
+ * @typedef {Object} Page
+ * @property {string=} previous
+ * @property {string=} next
+ * @property {T[]} results
+ */

Diff for: lib/types.js

@@ -7,6 +7,7 @@
   "bugs": "https://github.com/replicate/replicate-javascript/issues",
   "license": "Apache-2.0",
   "main": "index.js",
+  "types": "dist/types/index.d.ts",
   "engines": {
     "node": ">=18.0.0",
     "npm": ">=7.19.0",
@@ -17,7 +18,10 @@
     "check": "tsc",
     "format": "biome format . --write",
     "lint": "biome lint .",
-    "test": "REPLICATE_API_TOKEN=test-token jest"
+    "test": "REPLICATE_API_TOKEN=test-token jest",
+    "types": "tsc --target ES2022 --declaration --emitDeclarationOnly --allowJs --types node --outDir ./dist/types index.js ./lib/types.js",
+    "test:integration": "npm --prefix integration/commonjs test;npm --prefix integration/esm test;npm --prefix integration/typescript test",
+    "test:all": "npm run test && npm run test:integration"
   },
   "optionalDependencies": {
     "readable-stream": ">=4.0.0"

Diff for: package.json

@@ -2,9 +2,12 @@
   "compilerOptions": {
     "esModuleInterop": true,
     "noEmit": true,
-    "strict": true
+    "strict": true,
+    "allowJs": true,
   },
   "exclude": [
+    "dist",
+    "integration",
     "**/node_modules"
   ]
 }