@conorroberts/utils 0.0.42 → 0.0.44

package/dist/images.d.mts

@@ -26,6 +26,27 @@ interface CreateImageUrlResponse {
   errors: unknown[];
   messages: unknown[];
 }
+interface CloudflareImagesV1Response {
+  result: {
+    images: CloudflareImage[];
+  };
+  success: boolean;
+  errors: CloudflareApiError[];
+  messages: string[];
+}
+interface CloudflareImage {
+  id: string;
+  filename: string;
+  uploaded: string;
+  requireSignedURLs: boolean;
+  variants: string[];
+  meta?: Record<string, any>;
+  creator?: string | null;
+}
+interface CloudflareApiError {
+  code: number;
+  message: string;
+}
 declare class ImageUtils<ImageIds extends Record<string, any>> {
   private blacklist;
   private accountId;
@@ -55,8 +76,9 @@ declare class ImageUtils<ImageIds extends Record<string, any>> {
     id: string;
   }[]>;
   serverUpload(data: Blob, args: {
+    id?: string;
     apiKey: string;
-  }): Promise<any>;
+  }): Promise<CloudflareImagesV1Response>;
   upload(url: string, body: FormData): Promise<string>;
   delete(id: string, args: {
     apiKey: string;

package/dist/images.mjs

@@ -82,7 +82,7 @@ var ImageUtils = class {
 		formData.append("file", data, nanoid());
 		const headers = new Headers();
 		headers.set("Authorization", `Bearer ${args.apiKey}`);
-		return (await fetch(`https://api.cloudflare.com/client/v4/accounts/${this.accountId}/images/v1`, {
+		return await (await fetch(`https://api.cloudflare.com/client/v4/accounts/${this.accountId}/images/v1`, {
 			method: "POST",
 			headers,
 			body: formData

package/dist/images.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"images.mjs","names":[],"sources":["../src/images.ts"],"sourcesContent":["import { nanoid } from \"nanoid\";\nimport dayjs from \"dayjs\";\nimport { ofetch } from \"ofetch\";\n\nexport interface OptimizedImageOptions {\n  anim?: boolean;\n  background?: string;\n  blur?: number;\n  brightness?: number;\n  compression?: \"fast\"; // faster compression = larger file size\n  contrast?: number;\n  dpr?: number;\n  fit?: \"scale-down\" | \"contain\" | \"cover\" | \"crop\" | \"pad\";\n  format?: \"webp\" | \"avif\" | \"json\";\n  gamma?: number;\n  width?: number;\n  height?: number;\n  metadata?: \"keep\" | \"copyright\" | \"none\";\n  quality?: number;\n  rotate?: number;\n  sharpen?: number;\n}\n\nexport interface CreateImageUrlResponse {\n  result: {\n    id: string;\n    uploadURL: string;\n  };\n  success: boolean;\n  errors: unknown[];\n  messages: unknown[];\n}\n\ninterface UploadImageResponse {\n  result: {\n    id: string;\n    filename: string;\n    uploaded: string;\n    requireSignedURLs: boolean;\n    variants: string[];\n  };\n  success: boolean;\n  errors: unknown[];\n  messages: unknown[];\n}\n\nexport class ImageUtils<ImageIds extends Record<string, any>> {\n  private blacklist: string[] = [\"img.clerk.com\"];\n  private accountId: string;\n  private accountHash: string;\n  private _imageIds: ImageIds | undefined;\n\n  constructor(args: {\n    accountId: string;\n    accountHash: string;\n    blacklist?: string[];\n    imageIds?: ImageIds;\n  }) {\n    this.accountId = args.accountId;\n    this.accountHash = args.accountHash;\n\n    this._imageIds = args.imageIds;\n\n    if (args.blacklist) {\n      this.blacklist.push(...args.blacklist);\n    }\n  }\n\n  get imageIds() {\n    if (!this._imageIds) {\n      throw new Error(\"imageIds was not supplied in constructor\");\n    }\n\n    return this._imageIds;\n  }\n\n  public url(id: string) {\n    return `https://imagedelivery.net/${this.accountHash}/${id}/public`;\n  }\n\n  private isBlacklisted(url: string) {\n    return this.blacklist.some((u) => url.includes(u));\n  }\n\n  private isProtected(id: string) {\n    if (!this._imageIds) {\n      return false;\n    }\n\n    return Object.values(this._imageIds).some((e) => e === id);\n  }\n\n  /**\n   * Will only operate on images that have been uploaded via cloudflare images\n   */\n  public optimizeUrl(url: string, options: OptimizedImageOptions) {\n    if (this.isBlacklisted(url)) {\n      return url;\n    }\n\n    // Final format should look similar to: https://imagedelivery.net/<ACCOUNT_HASH>/<IMAGE_ID>/w=400,sharpen=3\n    return url.replace(\"public\", this.createImageOptionsString(options));\n  }\n\n  public optimizeId(id: string, options: OptimizedImageOptions) {\n    return this.optimizeUrl(this.url(id), options);\n  }\n\n  public createOptionsSearchParams(options: OptimizedImageOptions) {\n    const params = new URLSearchParams();\n\n    const pairs = Object.entries(options);\n\n    for (const [key, val] of pairs) {\n      if (val === undefined) {\n        continue;\n      }\n\n      params.set(key, val.toString());\n    }\n\n    return params;\n  }\n\n  public createImageOptionsString(options: OptimizedImageOptions) {\n    const params = this.createOptionsSearchParams(options);\n\n    return Array.from(params.entries())\n      .map(([key, val]) => `${key}=${val}`)\n      .join(\",\");\n  }\n\n  public async createUploadUrls(count: number, args: { apiKey: string }) {\n    if (count === 0) {\n      return [];\n    }\n\n    const headers = new Headers();\n    headers.set(\"Authorization\", `Bearer ${args.apiKey}`);\n\n    const urls = await Promise.all(\n      Array.from({ length: count }).map(async () => {\n        try {\n          const form = new FormData();\n          const id = nanoid();\n          form.append(\"id\", id);\n          form.append(\"expiry\", dayjs().add(5, \"minute\").toISOString());\n\n          const img = await ofetch<CreateImageUrlResponse>(\n            `https://api.cloudflare.com/client/v4/accounts/${this.accountId}/images/v2/direct_upload`,\n            { method: \"POST\", headers, body: form },\n          );\n\n          if (!img.success) {\n            throw new Error(\"Error uploading image\");\n          }\n\n          return { url: img.result.uploadURL, id };\n        } catch (e) {\n          console.error(\"Error uploading image\");\n          throw e;\n        }\n      }),\n    );\n\n    return urls;\n  }\n\n  public async serverUpload(data: Blob, args: { apiKey: string }) {\n    const formData = new FormData();\n    formData.append(\"file\", data, nanoid());\n\n    const headers = new Headers();\n    headers.set(\"Authorization\", `Bearer ${args.apiKey}`);\n\n    const response = await fetch(`https://api.cloudflare.com/client/v4/accounts/${this.accountId}/images/v1`, {\n      method: \"POST\",\n      headers,\n      body: formData,\n    });\n\n    return response.json();\n  }\n\n  public async upload(url: string, body: FormData) {\n    const fetchResponse = await ofetch<UploadImageResponse>(url, {\n      method: \"POST\",\n      body,\n    });\n\n    if (!fetchResponse.success) {\n      throw new Error(\"Failed to upload image\");\n    }\n\n    const downloadUrl = fetchResponse.result.variants[0];\n\n    if (!downloadUrl) {\n      throw new Error(\"Could not find download URL\");\n    }\n\n    return downloadUrl;\n  }\n\n  public async delete(id: string, args: { apiKey: string }) {\n    if (this.isProtected(id)) {\n      return { success: true };\n    }\n\n    try {\n      const headers = new Headers();\n      headers.set(\"Authorization\", `Bearer ${args.apiKey}`);\n\n      await ofetch(`https://api.cloudflare.com/client/v4/accounts/${this.accountId}/images/v1/${id}`, {\n        method: \"POST\",\n        headers,\n      });\n      return { success: true };\n    } catch {\n      return { success: false };\n    }\n  }\n\n  public async batchUpload(files: { file: File; url: { id: string; value: string } }[]) {\n    return await Promise.all(\n      files.map(async (e) => {\n        const formData = new FormData();\n        formData.append(\"file\", e.file);\n\n        const downloadUrl = await this.upload(e.url.value, formData);\n\n        return {\n          url: downloadUrl,\n          id: e.url.id,\n        };\n      }),\n    );\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"images.mjs","names":[],"sources":["../src/images.ts"],"sourcesContent":["import { nanoid } from \"nanoid\";\nimport dayjs from \"dayjs\";\nimport { ofetch } from \"ofetch\";\n\nexport interface OptimizedImageOptions {\n  anim?: boolean;\n  background?: string;\n  blur?: number;\n  brightness?: number;\n  compression?: \"fast\"; // faster compression = larger file size\n  contrast?: number;\n  dpr?: number;\n  fit?: \"scale-down\" | \"contain\" | \"cover\" | \"crop\" | \"pad\";\n  format?: \"webp\" | \"avif\" | \"json\";\n  gamma?: number;\n  width?: number;\n  height?: number;\n  metadata?: \"keep\" | \"copyright\" | \"none\";\n  quality?: number;\n  rotate?: number;\n  sharpen?: number;\n}\n\nexport interface CreateImageUrlResponse {\n  result: {\n    id: string;\n    uploadURL: string;\n  };\n  success: boolean;\n  errors: unknown[];\n  messages: unknown[];\n}\n\ninterface UploadImageResponse {\n  result: {\n    id: string;\n    filename: string;\n    uploaded: string;\n    requireSignedURLs: boolean;\n    variants: string[];\n  };\n  success: boolean;\n  errors: unknown[];\n  messages: unknown[];\n}\n\ninterface CloudflareImagesV1Response {\n  result: {\n    images: CloudflareImage[];\n  };\n  success: boolean;\n  errors: CloudflareApiError[];\n  messages: string[];\n}\n\ninterface CloudflareImage {\n  id: string; // Unique image identifier\n  filename: string; // Original filename\n  uploaded: string; // ISO 8601 date-time string\n  requireSignedURLs: boolean;\n  variants: string[]; // Array of URLs for the image variants\n  meta?: Record<string, any>; // User modifiable key-value store (max 1024 bytes)\n  creator?: string | null; // Internal user ID (optional)\n}\n\ninterface CloudflareApiError {\n  code: number;\n  message: string;\n}\n\nexport class ImageUtils<ImageIds extends Record<string, any>> {\n  private blacklist: string[] = [\"img.clerk.com\"];\n  private accountId: string;\n  private accountHash: string;\n  private _imageIds: ImageIds | undefined;\n\n  constructor(args: {\n    accountId: string;\n    accountHash: string;\n    blacklist?: string[];\n    imageIds?: ImageIds;\n  }) {\n    this.accountId = args.accountId;\n    this.accountHash = args.accountHash;\n\n    this._imageIds = args.imageIds;\n\n    if (args.blacklist) {\n      this.blacklist.push(...args.blacklist);\n    }\n  }\n\n  get imageIds() {\n    if (!this._imageIds) {\n      throw new Error(\"imageIds was not supplied in constructor\");\n    }\n\n    return this._imageIds;\n  }\n\n  public url(id: string) {\n    return `https://imagedelivery.net/${this.accountHash}/${id}/public`;\n  }\n\n  private isBlacklisted(url: string) {\n    return this.blacklist.some((u) => url.includes(u));\n  }\n\n  private isProtected(id: string) {\n    if (!this._imageIds) {\n      return false;\n    }\n\n    return Object.values(this._imageIds).some((e) => e === id);\n  }\n\n  /**\n   * Will only operate on images that have been uploaded via cloudflare images\n   */\n  public optimizeUrl(url: string, options: OptimizedImageOptions) {\n    if (this.isBlacklisted(url)) {\n      return url;\n    }\n\n    // Final format should look similar to: https://imagedelivery.net/<ACCOUNT_HASH>/<IMAGE_ID>/w=400,sharpen=3\n    return url.replace(\"public\", this.createImageOptionsString(options));\n  }\n\n  public optimizeId(id: string, options: OptimizedImageOptions) {\n    return this.optimizeUrl(this.url(id), options);\n  }\n\n  public createOptionsSearchParams(options: OptimizedImageOptions) {\n    const params = new URLSearchParams();\n\n    const pairs = Object.entries(options);\n\n    for (const [key, val] of pairs) {\n      if (val === undefined) {\n        continue;\n      }\n\n      params.set(key, val.toString());\n    }\n\n    return params;\n  }\n\n  public createImageOptionsString(options: OptimizedImageOptions) {\n    const params = this.createOptionsSearchParams(options);\n\n    return Array.from(params.entries())\n      .map(([key, val]) => `${key}=${val}`)\n      .join(\",\");\n  }\n\n  public async createUploadUrls(count: number, args: { apiKey: string }) {\n    if (count === 0) {\n      return [];\n    }\n\n    const headers = new Headers();\n    headers.set(\"Authorization\", `Bearer ${args.apiKey}`);\n\n    const urls = await Promise.all(\n      Array.from({ length: count }).map(async () => {\n        try {\n          const form = new FormData();\n          const id = nanoid();\n          form.append(\"id\", id);\n          form.append(\"expiry\", dayjs().add(5, \"minute\").toISOString());\n\n          const img = await ofetch<CreateImageUrlResponse>(\n            `https://api.cloudflare.com/client/v4/accounts/${this.accountId}/images/v2/direct_upload`,\n            { method: \"POST\", headers, body: form },\n          );\n\n          if (!img.success) {\n            throw new Error(\"Error uploading image\");\n          }\n\n          return { url: img.result.uploadURL, id };\n        } catch (e) {\n          console.error(\"Error uploading image\");\n          throw e;\n        }\n      }),\n    );\n\n    return urls;\n  }\n\n  public async serverUpload(data: Blob, args: { id?: string; apiKey: string }) {\n    const formData = new FormData();\n    formData.append(\"file\", data, nanoid());\n\n    const headers = new Headers();\n    headers.set(\"Authorization\", `Bearer ${args.apiKey}`);\n\n    const response = await fetch(`https://api.cloudflare.com/client/v4/accounts/${this.accountId}/images/v1`, {\n      method: \"POST\",\n      headers,\n      body: formData,\n    });\n\n    const json: CloudflareImagesV1Response = await response.json();\n\n    return json;\n  }\n\n  public async upload(url: string, body: FormData) {\n    const fetchResponse = await ofetch<UploadImageResponse>(url, {\n      method: \"POST\",\n      body,\n    });\n\n    if (!fetchResponse.success) {\n      throw new Error(\"Failed to upload image\");\n    }\n\n    const downloadUrl = fetchResponse.result.variants[0];\n\n    if (!downloadUrl) {\n      throw new Error(\"Could not find download URL\");\n    }\n\n    return downloadUrl;\n  }\n\n  public async delete(id: string, args: { apiKey: string }) {\n    if (this.isProtected(id)) {\n      return { success: true };\n    }\n\n    try {\n      const headers = new Headers();\n      headers.set(\"Authorization\", `Bearer ${args.apiKey}`);\n\n      await ofetch(`https://api.cloudflare.com/client/v4/accounts/${this.accountId}/images/v1/${id}`, {\n        method: \"POST\",\n        headers,\n      });\n      return { success: true };\n    } catch {\n      return { success: false };\n    }\n  }\n\n  public async batchUpload(files: { file: File; url: { id: string; value: string } }[]) {\n    return await Promise.all(\n      files.map(async (e) => {\n        const formData = new FormData();\n        formData.append(\"file\", e.file);\n\n        const downloadUrl = await this.upload(e.url.value, formData);\n\n        return {\n          url: downloadUrl,\n          id: e.url.id,\n        };\n      }),\n    );\n  }\n}\n"],"mappings":"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"}

package/dist/oxlint/jsx-component-pascal-case.d.mts

@@ -1,20 +1,20 @@
-import * as oxlint15 from "oxlint";
+import * as oxlint24 from "oxlint";
 
 //#region src/oxlint-plugins/jsx-component-pascal-case.d.ts
-declare const jsxComponentPascalCaseRule: oxlint15.Rule;
+declare const jsxComponentPascalCaseRule: oxlint24.Rule;
 declare namespace _default {
   namespace meta {
     let name: string;
   }
   let rules: {
-    "jsx-component-pascal-case": oxlint15.Rule;
+    "jsx-component-pascal-case": oxlint24.Rule;
   };
 }
-type RuleContext = oxlint15.Context;
-type ESTNode = oxlint15.ESTree.Node;
-type ESTExpression = oxlint15.ESTree.Expression;
-type ReturnStatementNode = oxlint15.ESTree.ReturnStatement;
-type FunctionLikeNode = oxlint15.ESTree.Function | oxlint15.ESTree.ArrowFunctionExpression;
+type RuleContext = oxlint24.Context;
+type ESTNode = oxlint24.ESTree.Node;
+type ESTExpression = oxlint24.ESTree.Expression;
+type ReturnStatementNode = oxlint24.ESTree.ReturnStatement;
+type FunctionLikeNode = oxlint24.ESTree.Function | oxlint24.ESTree.ArrowFunctionExpression;
 type FunctionContext = {
   node: FunctionLikeNode;
   name: string;

package/dist/oxlint/no-component-date-instantiation.d.mts

@@ -1,20 +1,20 @@
-import * as oxlint35 from "oxlint";
+import * as oxlint32 from "oxlint";
 
 //#region src/oxlint-plugins/no-component-date-instantiation.d.ts
-declare const noComponentDateInstantiationRule: oxlint35.Rule;
+declare const noComponentDateInstantiationRule: oxlint32.Rule;
 declare namespace _default {
   namespace meta {
     let name: string;
   }
   let rules: {
-    "no-component-date-instantiation": oxlint35.Rule;
+    "no-component-date-instantiation": oxlint32.Rule;
   };
 }
-type RuleContext = oxlint35.Context;
-type ESTNode = oxlint35.ESTree.Node;
-type NewExpressionNode = oxlint35.ESTree.NewExpression;
-type ReturnStatementNode = oxlint35.ESTree.ReturnStatement;
-type FunctionLikeNode = oxlint35.ESTree.Function | oxlint35.ESTree.ArrowFunctionExpression;
+type RuleContext = oxlint32.Context;
+type ESTNode = oxlint32.ESTree.Node;
+type NewExpressionNode = oxlint32.ESTree.NewExpression;
+type ReturnStatementNode = oxlint32.ESTree.ReturnStatement;
+type FunctionLikeNode = oxlint32.ESTree.Function | oxlint32.ESTree.ArrowFunctionExpression;
 type FunctionContext = {
   node: FunctionLikeNode;
   parent: FunctionContext | null;

package/dist/oxlint/no-emoji.d.mts

@@ -1,16 +1,16 @@
-import * as oxlint29 from "oxlint";
+import * as oxlint10 from "oxlint";
 
 //#region src/oxlint-plugins/no-emoji.d.ts
-declare const noEmojiRule: oxlint29.Rule;
+declare const noEmojiRule: oxlint10.Rule;
 declare namespace _default {
   namespace meta {
     let name: string;
   }
   let rules: {
-    "no-emoji": oxlint29.Rule;
+    "no-emoji": oxlint10.Rule;
   };
 }
-type ESTNode = oxlint29.ESTree.Node;
+type ESTNode = oxlint10.ESTree.Node;
 //#endregion
 export { ESTNode, _default as default, noEmojiRule };
 //# sourceMappingURL=no-emoji.d.mts.map

package/dist/oxlint/no-finally.d.mts

@@ -1,16 +1,16 @@
-import * as oxlint12 from "oxlint";
+import * as oxlint18 from "oxlint";
 
 //#region src/oxlint-plugins/no-finally.d.ts
-declare const noFinallyRule: oxlint12.Rule;
+declare const noFinallyRule: oxlint18.Rule;
 declare namespace _default {
   namespace meta {
     let name: string;
   }
   let rules: {
-    "no-finally": oxlint12.Rule;
+    "no-finally": oxlint18.Rule;
   };
 }
-type ESTNode = oxlint12.ESTree.Node;
+type ESTNode = oxlint18.ESTree.Node;
 //#endregion
 export { ESTNode, _default as default, noFinallyRule };
 //# sourceMappingURL=no-finally.d.mts.map

package/dist/oxlint/no-react-namespace.d.mts

@@ -1,16 +1,16 @@
-import * as oxlint26 from "oxlint";
+import * as oxlint21 from "oxlint";
 
 //#region src/oxlint-plugins/no-react-namespace.d.ts
-declare const noReactNamespaceRule: oxlint26.Rule;
+declare const noReactNamespaceRule: oxlint21.Rule;
 declare namespace _default {
   namespace meta {
     let name: string;
   }
   let rules: {
-    "no-react-namespace": oxlint26.Rule;
+    "no-react-namespace": oxlint21.Rule;
   };
 }
-type ESTNode = oxlint26.ESTree.Node;
+type ESTNode = oxlint21.ESTree.Node;
 //#endregion
 export { ESTNode, _default as default, noReactNamespaceRule };
 //# sourceMappingURL=no-react-namespace.d.mts.map

package/dist/oxlint/no-switch-plugin.d.mts

@@ -1,4 +1,4 @@
-import * as oxlint10 from "oxlint";
+import * as oxlint16 from "oxlint";
 
 //#region src/oxlint-plugins/no-switch-plugin.d.ts
 declare namespace _default {
@@ -6,10 +6,10 @@ declare namespace _default {
     let name: string;
   }
   let rules: {
-    "no-switch": oxlint10.Rule;
+    "no-switch": oxlint16.Rule;
   };
 }
-type ESTNode = oxlint10.ESTree.Node;
+type ESTNode = oxlint16.ESTree.Node;
 //#endregion
 export { ESTNode, _default as default };
 //# sourceMappingURL=no-switch-plugin.d.mts.map

package/dist/oxlint/no-top-level-let.d.mts

@@ -1,16 +1,16 @@
-import * as oxlint32 from "oxlint";
+import * as oxlint13 from "oxlint";
 
 //#region src/oxlint-plugins/no-top-level-let.d.ts
-declare const noTopLevelLetRule: oxlint32.Rule;
+declare const noTopLevelLetRule: oxlint13.Rule;
 declare namespace _default {
   namespace meta {
     let name: string;
   }
   let rules: {
-    "no-top-level-let": oxlint32.Rule;
+    "no-top-level-let": oxlint13.Rule;
   };
 }
-type ESTNode = oxlint32.ESTree.Node;
+type ESTNode = oxlint13.ESTree.Node;
 //#endregion
 export { ESTNode, _default as default, noTopLevelLetRule };
 //# sourceMappingURL=no-top-level-let.d.mts.map

package/dist/oxlint/no-type-cast.d.mts

@@ -1,16 +1,16 @@
-import * as oxlint23 from "oxlint";
+import * as oxlint40 from "oxlint";
 
 //#region src/oxlint-plugins/no-type-cast.d.ts
-declare const noTypeCastRule: oxlint23.Rule;
+declare const noTypeCastRule: oxlint40.Rule;
 declare namespace _default {
   namespace meta {
     let name: string;
   }
   let rules: {
-    "no-type-cast": oxlint23.Rule;
+    "no-type-cast": oxlint40.Rule;
   };
 }
-type ESTNode = oxlint23.ESTree.Node;
+type ESTNode = oxlint40.ESTree.Node;
 //#endregion
 export { ESTNode, _default as default, noTypeCastRule };
 //# sourceMappingURL=no-type-cast.d.mts.map

package/dist/react.d.mts

@@ -0,0 +1,57 @@
+//#region src/react/useStableCallback.d.ts
+type AnyFunction = (...args: any[]) => any;
+/**
+ * Creates a stable callback that always calls the latest version of the function.
+ * Useful for callbacks that need to be used in dependency arrays but should always
+ * execute the most recent version of the callback.
+ */
+declare const useStableCallback: <T extends AnyFunction>(callback: T) => T;
+//#endregion
+//#region src/react/useOnce.d.ts
+/**
+ * Runs a callback only once when a condition becomes truthy.
+ * The callback is stabilized internally to always reference the latest version.
+ *
+ * @param condition - When truthy (evaluated via Boolean()), the callback will be executed (only once).
+ * @param callback - The function to run once when the condition is met.
+ *
+ * @example
+ * ```tsx
+ * const isReady = true;
+ * useOnce(isReady, () => {
+ *   console.log("Ready!");
+ * });
+ * ```
+ */
+declare const useOnce: (condition: unknown, callback: () => void) => void;
+//#endregion
+//#region src/react/useLocalOnce.d.ts
+/**
+ * Runs a callback only once when a condition becomes truthy, executing synchronously
+ * during render. The callback is stabilized internally to always reference the latest version.
+ *
+ * Unlike `useOnce`, this runs at the top level of the hook (not in useEffect),
+ * making it suitable for state updates that need to happen synchronously during render.
+ *
+ * @param condition - When truthy (evaluated via Boolean()), the callback will be executed (only once).
+ * @param callback - The function to run once when the condition is met.
+ *
+ * @example
+ * ```tsx
+ * const user: User | null = getUser();
+ * useLocalOnce(user, () => {
+ *   setState(user.name);
+ * });
+ * ```
+ */
+declare const useLocalOnce: (condition: unknown, callback: () => void) => void;
+//#endregion
+//#region src/react/useOnUnmount.d.ts
+/**
+ * Calls the given callback when the component unmounts.
+ * Uses useStableCallback internally to ensure the latest version is called.
+ */
+declare const useOnUnmount: (callback: () => void) => void;
+//#endregion
+export { useLocalOnce, useOnUnmount, useOnce, useStableCallback };
+//# sourceMappingURL=react.d.mts.map

package/dist/react.mjs

@@ -0,0 +1,91 @@
+import { useCallback, useEffect, useRef } from "react";
+
+//#region src/react/useStableCallback.ts
+/**
+* Creates a stable callback that always calls the latest version of the function.
+* Useful for callbacks that need to be used in dependency arrays but should always
+* execute the most recent version of the callback.
+*/
+const useStableCallback = (callback) => {
+	const callbackRef = useRef(callback);
+	callbackRef.current = callback;
+	return useCallback((...args) => {
+		return callbackRef.current(...args);
+	}, []);
+};
+
+//#endregion
+//#region src/react/useOnce.ts
+/**
+* Runs a callback only once when a condition becomes truthy.
+* The callback is stabilized internally to always reference the latest version.
+*
+* @param condition - When truthy (evaluated via Boolean()), the callback will be executed (only once).
+* @param callback - The function to run once when the condition is met.
+*
+* @example
+* ```tsx
+* const isReady = true;
+* useOnce(isReady, () => {
+*   console.log("Ready!");
+* });
+* ```
+*/
+const useOnce = (condition, callback) => {
+	const hasRunRef = useRef(false);
+	const stableCallback = useStableCallback(callback);
+	useEffect(() => {
+		if (Boolean(condition) && !hasRunRef.current) {
+			hasRunRef.current = true;
+			stableCallback();
+		}
+	}, [condition, stableCallback]);
+};
+
+//#endregion
+//#region src/react/useLocalOnce.ts
+/**
+* Runs a callback only once when a condition becomes truthy, executing synchronously
+* during render. The callback is stabilized internally to always reference the latest version.
+*
+* Unlike `useOnce`, this runs at the top level of the hook (not in useEffect),
+* making it suitable for state updates that need to happen synchronously during render.
+*
+* @param condition - When truthy (evaluated via Boolean()), the callback will be executed (only once).
+* @param callback - The function to run once when the condition is met.
+*
+* @example
+* ```tsx
+* const user: User | null = getUser();
+* useLocalOnce(user, () => {
+*   setState(user.name);
+* });
+* ```
+*/
+const useLocalOnce = (condition, callback) => {
+	const hasRunRef = useRef(false);
+	const stableCallback = useStableCallback(callback);
+	if (Boolean(condition) && !hasRunRef.current) {
+		hasRunRef.current = true;
+		stableCallback();
+	}
+};
+
+//#endregion
+//#region src/react/useOnUnmount.ts
+/**
+* Calls the given callback when the component unmounts.
+* Uses useStableCallback internally to ensure the latest version is called.
+*/
+const useOnUnmount = (callback) => {
+	const stableCallback = useStableCallback(callback);
+	useEffect(() => {
+		return () => {
+			stableCallback();
+		};
+	}, [stableCallback]);
+};
+
+//#endregion
+export { useLocalOnce, useOnUnmount, useOnce, useStableCallback };
+//# sourceMappingURL=react.mjs.map

package/dist/react.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.mjs","names":[],"sources":["../src/react/useStableCallback.ts","../src/react/useOnce.ts","../src/react/useLocalOnce.ts","../src/react/useOnUnmount.ts"],"sourcesContent":["// oxlint-disable no-explicit-any\r\n\r\nimport { useCallback, useRef } from \"react\";\r\n\r\ntype AnyFunction = (...args: any[]) => any;\r\ntype AnyArgs = any[];\r\n\r\n/**\r\n * Creates a stable callback that always calls the latest version of the function.\r\n * Useful for callbacks that need to be used in dependency arrays but should always\r\n * execute the most recent version of the callback.\r\n */\r\nexport const useStableCallback = <T extends AnyFunction>(callback: T): T => {\r\n  const callbackRef = useRef(callback);\r\n\r\n  // Update the ref on every render\r\n  callbackRef.current = callback;\r\n\r\n  return useCallback((...args: AnyArgs) => {\r\n    return callbackRef.current(...args);\r\n  }, []) as T;\r\n};\r\n","import { useEffect, useRef } from \"react\";\r\nimport { useStableCallback } from \"./useStableCallback\";\r\n\r\n/**\r\n * Runs a callback only once when a condition becomes truthy.\r\n * The callback is stabilized internally to always reference the latest version.\r\n *\r\n * @param condition - When truthy (evaluated via Boolean()), the callback will be executed (only once).\r\n * @param callback - The function to run once when the condition is met.\r\n *\r\n * @example\r\n * ```tsx\r\n * const isReady = true;\r\n * useOnce(isReady, () => {\r\n *   console.log(\"Ready!\");\r\n * });\r\n * ```\r\n */\r\nexport const useOnce = (condition: unknown, callback: () => void): void => {\r\n  const hasRunRef = useRef(false);\r\n  const stableCallback = useStableCallback(callback);\r\n\r\n  useEffect(() => {\r\n    if (Boolean(condition) && !hasRunRef.current) {\r\n      hasRunRef.current = true;\r\n      stableCallback();\r\n    }\r\n  }, [condition, stableCallback]);\r\n};\r\n","import { useRef } from \"react\";\r\nimport { useStableCallback } from \"./useStableCallback\";\r\n\r\n/**\r\n * Runs a callback only once when a condition becomes truthy, executing synchronously\r\n * during render. The callback is stabilized internally to always reference the latest version.\r\n *\r\n * Unlike `useOnce`, this runs at the top level of the hook (not in useEffect),\r\n * making it suitable for state updates that need to happen synchronously during render.\r\n *\r\n * @param condition - When truthy (evaluated via Boolean()), the callback will be executed (only once).\r\n * @param callback - The function to run once when the condition is met.\r\n *\r\n * @example\r\n * ```tsx\r\n * const user: User | null = getUser();\r\n * useLocalOnce(user, () => {\r\n *   setState(user.name);\r\n * });\r\n * ```\r\n */\r\nexport const useLocalOnce = (condition: unknown, callback: () => void): void => {\r\n  const hasRunRef = useRef(false);\r\n  const stableCallback = useStableCallback(callback);\r\n\r\n  if (Boolean(condition) && !hasRunRef.current) {\r\n    hasRunRef.current = true;\r\n    stableCallback();\r\n  }\r\n};\r\n","import { useEffect } from \"react\";\r\nimport { useStableCallback } from \"./useStableCallback\";\r\n\r\n/**\r\n * Calls the given callback when the component unmounts.\r\n * Uses useStableCallback internally to ensure the latest version is called.\r\n */\r\nexport const useOnUnmount = (callback: () => void): void => {\r\n  const stableCallback = useStableCallback(callback);\r\n\r\n  useEffect(() => {\r\n    return () => {\r\n      stableCallback();\r\n    };\r\n  }, [stableCallback]);\r\n};\r\n"],"mappings":";;;;;;;;AAYA,MAAa,qBAA4C,aAAmB;CAC1E,MAAM,cAAc,OAAO,SAAS;AAGpC,aAAY,UAAU;AAEtB,QAAO,aAAa,GAAG,SAAkB;AACvC,SAAO,YAAY,QAAQ,GAAG,KAAK;IAClC,EAAE,CAAC;;;;;;;;;;;;;;;;;;;;ACFR,MAAa,WAAW,WAAoB,aAA+B;CACzE,MAAM,YAAY,OAAO,MAAM;CAC/B,MAAM,iBAAiB,kBAAkB,SAAS;AAElD,iBAAgB;AACd,MAAI,QAAQ,UAAU,IAAI,CAAC,UAAU,SAAS;AAC5C,aAAU,UAAU;AACpB,mBAAgB;;IAEjB,CAAC,WAAW,eAAe,CAAC;;;;;;;;;;;;;;;;;;;;;;;ACNjC,MAAa,gBAAgB,WAAoB,aAA+B;CAC9E,MAAM,YAAY,OAAO,MAAM;CAC/B,MAAM,iBAAiB,kBAAkB,SAAS;AAElD,KAAI,QAAQ,UAAU,IAAI,CAAC,UAAU,SAAS;AAC5C,YAAU,UAAU;AACpB,kBAAgB;;;;;;;;;;ACpBpB,MAAa,gBAAgB,aAA+B;CAC1D,MAAM,iBAAiB,kBAAkB,SAAS;AAElD,iBAAgB;AACd,eAAa;AACX,mBAAgB;;IAEjB,CAAC,eAAe,CAAC"}

package/package.json

@@ -15,6 +15,10 @@
       "types": "./dist/images.d.mts",
       "default": "./dist/images.mjs"
     },
+    "./react": {
+      "types": "./dist/react.d.mts",
+      "default": "./dist/react.mjs"
+    },
     "./oxlint/config": {
       "default": "./dist/oxlint/config.mjson"
     },
@@ -63,17 +67,22 @@
     "remeda": "2.32.0",
     "valibot": "1.1.0"
   },
-  "keywords": [],
-  "author": "",
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
   "license": "ISC",
   "devDependencies": {
     "@biomejs/biome": "1.8.3",
-    "@types/node": "24.10.0",
+    "@testing-library/react": "16.3.0",
+    "@types/node": "25.0.1",
+    "@types/react": "19.2.7",
+    "react": "19.2.3",
     "tsdown": "0.17.2",
     "typescript": "5.9.3",
     "vitest": "4.0.15"
   },
-  "version": "0.0.42",
+  "version": "0.0.44",
   "scripts": {
     "dev": "tsdown --watch",
     "build": "tsc --noEmit && tsdown",