@symbiote-native/image-manipulator 0.1.0

package/src/core/native-module.ts

@@ -0,0 +1,40 @@
+import {
+  requireNativeModule,
+  SharedObject,
+  SharedRef,
+} from 'expo-modules-core';
+import type { IImageResult, ISaveOptions } from './types';
+
+const EXPO_IMAGE_MANIPULATOR_MODULE_NAME = 'ExpoImageManipulator';
+
+export declare class NativeImageRef extends SharedRef<'image'> {
+  width: number;
+  height: number;
+  saveAsync(options?: ISaveOptions): Promise<IImageResult>;
+}
+
+export declare class NativeImageManipulatorContext extends SharedObject {
+  resize(size: {
+    width?: number | null;
+    height?: number | null;
+  }): NativeImageManipulatorContext;
+  rotate(degrees: number): NativeImageManipulatorContext;
+  flip(flipType: 'vertical' | 'horizontal'): NativeImageManipulatorContext;
+  crop(rect: {
+    originX: number;
+    originY: number;
+    width: number;
+    height: number;
+  }): NativeImageManipulatorContext;
+  reset(): NativeImageManipulatorContext;
+  renderAsync(): Promise<NativeImageRef>;
+}
+
+export type INativeImageManipulatorModule = {
+  manipulate(source: string | NativeImageRef): NativeImageManipulatorContext;
+};
+
+export const expoImageManipulator =
+  requireNativeModule<INativeImageManipulatorModule>(
+    EXPO_IMAGE_MANIPULATOR_MODULE_NAME,
+  );

package/src/core/types.ts

@@ -0,0 +1,47 @@
+export enum FlipType {
+  Vertical = 'vertical',
+  Horizontal = 'horizontal',
+}
+
+export enum SaveFormat {
+  JPEG = 'jpeg',
+  PNG = 'png',
+  WEBP = 'webp',
+}
+
+export type IActionResize = {
+  /** Provide only one of `width`/`height` to preserve the image's ratio. */
+  resize: { width?: number; height?: number };
+};
+
+export type IActionRotate = {
+  /** Degrees, clockwise when positive, counter-clockwise when negative. */
+  rotate: number;
+};
+
+export type IActionFlip = {
+  flip: FlipType;
+};
+
+export type IActionCrop = {
+  crop: { originX: number; originY: number; width: number; height: number };
+};
+
+/** @deprecated use `manipulate(source)` instead. */
+export type IAction = IActionResize | IActionRotate | IActionFlip | IActionCrop;
+
+export type ISaveOptions = {
+  base64?: boolean;
+  /** `0.0`-`1.0`; `1` is no compression (highest quality). Default `1`. */
+  compress?: number;
+  /** Default `SaveFormat.JPEG`. */
+  format?: SaveFormat;
+};
+
+export type IImageResult = {
+  uri: string;
+  width: number;
+  height: number;
+  /** Set only when `base64` was truthy in `ISaveOptions`. */
+  base64?: string;
+};

package/src/core/validators.ts

@@ -0,0 +1,128 @@
+import { FlipType, SaveFormat } from './types';
+import type {
+  IAction,
+  IActionCrop,
+  IActionFlip,
+  IActionResize,
+  IActionRotate,
+  ISaveOptions,
+} from './types';
+
+const SUPPORTED_ACTION_TYPES = ['crop', 'flip', 'rotate', 'resize'];
+
+export function validateArguments(
+  uri: string,
+  actions: IAction[],
+  saveOptions: ISaveOptions,
+): void {
+  validateUri(uri);
+  validateActions(actions);
+  validateSaveOptions(saveOptions);
+}
+
+export function validateUri(uri: string): void {
+  if (typeof uri !== 'string') {
+    throw new TypeError('The "uri" argument must be a string');
+  }
+}
+
+export function validateActions(actions: IAction[]): void {
+  if (!Array.isArray(actions)) {
+    throw new TypeError('The "actions" argument must be an array');
+  }
+  for (const action of actions) {
+    if (typeof action !== 'object' || action === null) {
+      throw new TypeError('Action must be an object');
+    }
+    const actionKeys = Object.keys(action);
+    if (actionKeys.length !== 1) {
+      throw new TypeError(
+        `Single action must contain exactly one transformation: ${SUPPORTED_ACTION_TYPES.join(', ')}`,
+      );
+    }
+    const actionType = actionKeys[0];
+    if (!SUPPORTED_ACTION_TYPES.includes(actionType)) {
+      throw new TypeError(`Unsupported action type: ${actionType}`);
+    }
+    if ('crop' in action) {
+      validateCropAction(action);
+    } else if ('flip' in action) {
+      validateFlipAction(action);
+    } else if ('rotate' in action) {
+      validateRotateAction(action);
+    } else if ('resize' in action) {
+      validateResizeAction(action);
+    }
+  }
+}
+
+function validateCropAction(action: IActionCrop): void {
+  const isValid =
+    typeof action.crop === 'object' &&
+    action.crop !== null &&
+    typeof action.crop.originX === 'number' &&
+    typeof action.crop.originY === 'number' &&
+    typeof action.crop.width === 'number' &&
+    typeof action.crop.height === 'number';
+  if (!isValid) {
+    throw new TypeError(
+      'Crop action must be an object of shape { originX: number; originY: number; width: number; height: number }',
+    );
+  }
+}
+
+function validateFlipAction(action: IActionFlip): void {
+  if (
+    typeof action.flip !== 'string' ||
+    ![FlipType.Horizontal, FlipType.Vertical].includes(action.flip)
+  ) {
+    throw new TypeError(`Unsupported flip type: ${action.flip}`);
+  }
+}
+
+function validateRotateAction(action: IActionRotate): void {
+  if (typeof action.rotate !== 'number') {
+    throw new TypeError('Rotation must be a number');
+  }
+}
+
+function validateResizeAction(action: IActionResize): void {
+  const isValid =
+    typeof action.resize === 'object' &&
+    action.resize !== null &&
+    (typeof action.resize.width === 'number' ||
+      action.resize.width === undefined) &&
+    (typeof action.resize.height === 'number' ||
+      action.resize.height === undefined);
+  if (!isValid) {
+    throw new TypeError(
+      'Resize action must be an object of shape { width?: number; height?: number }',
+    );
+  }
+}
+
+export function validateSaveOptions({
+  base64,
+  compress,
+  format,
+}: ISaveOptions): void {
+  if (base64 !== undefined && typeof base64 !== 'boolean') {
+    throw new TypeError('The "base64" argument must be a boolean');
+  }
+  if (compress !== undefined) {
+    if (typeof compress !== 'number') {
+      throw new TypeError('The "compress" argument must be a number');
+    }
+    if (compress < 0 || compress > 1) {
+      throw new TypeError(
+        'The "compress" argument must be a number between 0 and 1',
+      );
+    }
+  }
+  const allowedFormats = [SaveFormat.JPEG, SaveFormat.PNG, SaveFormat.WEBP];
+  if (format !== undefined && !allowedFormats.includes(format)) {
+    throw new TypeError(
+      `The "format" argument must be one of: ${allowedFormats.join(', ')}`,
+    );
+  }
+}

package/src/react/index.ts

@@ -0,0 +1,2 @@
+export * from '../core';
+export { useImageManipulator } from './use-image-manipulator';

package/src/react/use-image-manipulator.ts

@@ -0,0 +1,14 @@
+import { createResourceHook } from '@symbiote-native/react';
+import type { IImageManipulatorContext, IImageRef } from '../core';
+import { createImageManipulatorResourceController } from '../core/manipulator-resource-controller';
+
+const useManipulatorResource = createResourceHook(
+  createImageManipulatorResourceController,
+);
+
+/** React twin of `expo-image-manipulator`'s `useImageManipulator` */
+export function useImageManipulator(
+  source: string | IImageRef,
+): IImageManipulatorContext {
+  return useManipulatorResource(source);
+}

package/src/solid/index.ts

@@ -0,0 +1,2 @@
+export * from '../core';
+export { useImageManipulator } from './use-image-manipulator';

package/src/solid/use-image-manipulator.ts

@@ -0,0 +1,15 @@
+import type { Accessor } from 'solid-js';
+import { createResourceHook } from '@symbiote-native/solid';
+import type { IImageManipulatorContext, IImageRef } from '../core';
+import { createImageManipulatorResourceController } from '../core/manipulator-resource-controller';
+
+const useManipulatorResource = createResourceHook(
+  createImageManipulatorResourceController,
+);
+
+/** Solid twin of `expo-image-manipulator`'s `useImageManipulator` */
+export function useImageManipulator(
+  source: Accessor<string | IImageRef>,
+): Accessor<IImageManipulatorContext> {
+  return useManipulatorResource(() => [source()]);
+}

package/src/svelte/index.ts

@@ -0,0 +1,2 @@
+export * from '../core';
+export { useImageManipulator } from './use-image-manipulator.svelte';

package/src/svelte/svelte-ambient.d.ts

@@ -0,0 +1,3 @@
+// Pulls svelte's ambient globals ($state/$effect/...) into this package's tsc program,
+// same fix as `packages/navigation/src/svelte/svelte-ambient.d.ts`
+/// <reference types="svelte" />

package/src/svelte/svelte-compile.test-helper.ts

@@ -0,0 +1,7 @@
+// Re-exports the existing harness instead of a third copy (packages/sqlite and
+// packages/navigation already carry one, not part of either package's public exports)
+export {
+  createSvelteHarness,
+  loadComponent,
+  type ISvelteHarness,
+} from '../../../sqlite/src/svelte/svelte-compile.test-helper';

package/src/svelte/use-image-manipulator.svelte.ts

@@ -0,0 +1,19 @@
+// Svelte twin of `expo-image-manipulator`'s `useImageManipulator`
+
+import { createResourceHook } from '@symbiote-native/svelte/runes/create-resource-hook';
+import type { IImageManipulatorContext, IImageRef } from '../core';
+import { createImageManipulatorResourceController } from '../core/manipulator-resource-controller';
+
+export type IUseImageManipulatorResult = {
+  readonly current: IImageManipulatorContext;
+};
+
+const useManipulatorResource = createResourceHook(
+  createImageManipulatorResourceController,
+);
+
+export function useImageManipulator(
+  getSource: () => string | IImageRef,
+): IUseImageManipulatorResult {
+  return useManipulatorResource(() => [getSource()]);
+}

package/src/vue/index.ts

@@ -0,0 +1,2 @@
+export * from '../core';
+export { useImageManipulator } from './use-image-manipulator';

package/src/vue/use-image-manipulator.ts

@@ -0,0 +1,19 @@
+import {
+  toValue,
+  type ComputedRef,
+  type MaybeRefOrGetter,
+} from '@vue/runtime-core';
+import { createResourceHook } from '@symbiote-native/vue';
+import type { IImageManipulatorContext, IImageRef } from '../core';
+import { createImageManipulatorResourceController } from '../core/manipulator-resource-controller';
+
+const useManipulatorResource = createResourceHook(
+  createImageManipulatorResourceController,
+);
+
+/** Vue twin of `expo-image-manipulator`'s `useImageManipulator` */
+export function useImageManipulator(
+  source: MaybeRefOrGetter<string | IImageRef>,
+): ComputedRef<IImageManipulatorContext> {
+  return useManipulatorResource(() => [toValue(source)]);
+}