react-native-ble-nitro 1.0.0-alpha.1

package/src/compatibility/deviceWrapper.ts

@@ -0,0 +1,427 @@
+/**
+ * Device wrapper for compatibility
+ * 
+ * Wraps Nitro Device objects to provide the original react-native-ble-plx API
+ */
+
+import type { Device as NitroDevice } from '../specs/Device.nitro';
+import type { 
+  NativeDevice, 
+  UUID, 
+  Base64, 
+  DeviceId,
+  TransactionId,
+  ConnectionPriority,
+  ConnectionOptions,
+  ServiceDataEntry,
+  NativeService,
+  NativeCharacteristic,
+  NativeDescriptor,
+  CharacteristicSubscriptionType,
+  Subscription
+} from '../specs/types';
+import { serviceDataArrayToMap } from './serviceData';
+import { 
+  normalizeCharacteristicSubscriptionType,
+  stateToString,
+  characteristicSubscriptionTypeToString 
+} from './enums';
+
+/**
+ * Device wrapper that provides react-native-ble-plx compatibility
+ * Maps Nitro device properties to the expected API surface
+ */
+export class DeviceWrapper {
+  constructor(private nitroDevice: NitroDevice | any) {}
+
+  // Device identification
+  get id(): DeviceId {
+    return this.nitroDevice.id;
+  }
+
+  // Map deviceName back to name for compatibility
+  get name(): string | null {
+    return this.nitroDevice.deviceName || null;
+  }
+
+  get rssi(): number | null {
+    return this.nitroDevice.rssi || null;
+  }
+
+  get mtu(): number {
+    return this.nitroDevice.mtu;
+  }
+
+  // Advertisement data
+  get manufacturerData(): Base64 | null {
+    return this.nitroDevice.manufacturerData || null;
+  }
+
+  get rawScanRecord(): Base64 {
+    return this.nitroDevice.rawScanRecord;
+  }
+
+  // Convert ServiceDataEntry[] back to { [uuid: string]: Base64 }
+  get serviceData(): { [uuid: string]: Base64 } | null {
+    return serviceDataArrayToMap(this.nitroDevice.serviceData || null);
+  }
+
+  get serviceUUIDs(): UUID[] | null {
+    return this.nitroDevice.serviceUUIDs || null;
+  }
+
+  get localName(): string | null {
+    return this.nitroDevice.localName || null;
+  }
+
+  get txPowerLevel(): number | null {
+    return this.nitroDevice.txPowerLevel || null;
+  }
+
+  get solicitedServiceUUIDs(): UUID[] | null {
+    return this.nitroDevice.solicitedServiceUUIDs || null;
+  }
+
+  get isConnectable(): boolean | null {
+    return this.nitroDevice.isConnectable || null;
+  }
+
+  get overflowServiceUUIDs(): UUID[] | null {
+    return this.nitroDevice.overflowServiceUUIDs || null;
+  }
+
+  // Connection management methods
+  async requestConnectionPriority(
+    connectionPriority: ConnectionPriority,
+    transactionId?: TransactionId
+  ): Promise<DeviceWrapper> {
+    const result = await this.nitroDevice.requestConnectionPriority(connectionPriority, transactionId);
+    return new DeviceWrapper(result);
+  }
+
+  async readRSSI(transactionId?: TransactionId): Promise<DeviceWrapper> {
+    const result = await this.nitroDevice.readRSSI(transactionId);
+    return new DeviceWrapper(result);
+  }
+
+  async requestMTU(mtu: number, transactionId?: TransactionId): Promise<DeviceWrapper> {
+    const result = await this.nitroDevice.requestMTU(mtu, transactionId);
+    return new DeviceWrapper(result);
+  }
+
+  async connect(options?: Partial<ConnectionOptions>): Promise<DeviceWrapper> {
+    // Provide defaults for required fields in Nitro interface
+    const connectionOptions: ConnectionOptions = {
+      autoConnect: options?.autoConnect ?? false,
+      requestMTU: options?.requestMTU ?? 23,
+      timeout: options?.timeout ?? 0,
+    };
+
+    const result = await this.nitroDevice.connect(connectionOptions);
+    return new DeviceWrapper(result);
+  }
+
+  async cancelConnection(): Promise<DeviceWrapper> {
+    const result = await this.nitroDevice.cancelConnection();
+    return new DeviceWrapper(result);
+  }
+
+  async isConnected(): Promise<boolean> {
+    return await this.nitroDevice.isConnected();
+  }
+
+  onDisconnected(listener: (error: any | null, device: DeviceWrapper) => void): Subscription {
+    return this.nitroDevice.onDisconnected((error: any, device: any) => {
+      listener(error, new DeviceWrapper(device));
+    });
+  }
+
+  // Service discovery
+  async discoverAllServicesAndCharacteristics(transactionId?: TransactionId): Promise<DeviceWrapper> {
+    const result = await this.nitroDevice.discoverAllServicesAndCharacteristics(transactionId);
+    return new DeviceWrapper(result);
+  }
+
+  async services(): Promise<ServiceWrapper[]> {
+    const services = await this.nitroDevice.services();
+    return services.map((service: any) => new ServiceWrapper(service, this.nitroDevice));
+  }
+
+  // Characteristic operations
+  async characteristicsForService(serviceUUID: UUID): Promise<CharacteristicWrapper[]> {
+    const characteristics = await this.nitroDevice.characteristicsForService(serviceUUID);
+    return characteristics.map((char: any) => new CharacteristicWrapper(char, this.nitroDevice));
+  }
+
+  async readCharacteristicForService(
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    transactionId?: TransactionId
+  ): Promise<CharacteristicWrapper> {
+    const result = await this.nitroDevice.readCharacteristicForService(
+      serviceUUID, 
+      characteristicUUID, 
+      transactionId
+    );
+    return new CharacteristicWrapper(result, this.nitroDevice);
+  }
+
+  async writeCharacteristicWithResponseForService(
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    valueBase64: Base64,
+    transactionId?: TransactionId
+  ): Promise<CharacteristicWrapper> {
+    const result = await this.nitroDevice.writeCharacteristicWithResponseForService(
+      serviceUUID,
+      characteristicUUID,
+      valueBase64,
+      transactionId
+    );
+    return new CharacteristicWrapper(result, this.nitroDevice);
+  }
+
+  async writeCharacteristicWithoutResponseForService(
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    valueBase64: Base64,
+    transactionId?: TransactionId
+  ): Promise<CharacteristicWrapper> {
+    const result = await this.nitroDevice.writeCharacteristicWithoutResponseForService(
+      serviceUUID,
+      characteristicUUID,
+      valueBase64,
+      transactionId
+    );
+    return new CharacteristicWrapper(result, this.nitroDevice);
+  }
+
+  monitorCharacteristicForService(
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    listener: (error: any | null, characteristic: CharacteristicWrapper | null) => void,
+    transactionId?: TransactionId,
+    subscriptionType?: 'notification' | 'indication'
+  ): Subscription {
+    const nitroSubscriptionType = subscriptionType 
+      ? normalizeCharacteristicSubscriptionType(subscriptionType)
+      : undefined;
+
+    return this.nitroDevice.monitorCharacteristicForService(
+      serviceUUID,
+      characteristicUUID,
+      (error: any, characteristic: any) => {
+        listener(
+          error, 
+          characteristic ? new CharacteristicWrapper(characteristic, this.nitroDevice) : null
+        );
+      },
+      transactionId,
+      nitroSubscriptionType
+    );
+  }
+
+  // Descriptor operations
+  async descriptorsForService(
+    serviceUUID: UUID,
+    characteristicUUID: UUID
+  ): Promise<DescriptorWrapper[]> {
+    const descriptors = await this.nitroDevice.descriptorsForService(serviceUUID, characteristicUUID);
+    return descriptors.map((desc: any) => new DescriptorWrapper(desc, this.nitroDevice));
+  }
+
+  async readDescriptorForService(
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    descriptorUUID: UUID,
+    transactionId?: TransactionId
+  ): Promise<DescriptorWrapper> {
+    const result = await this.nitroDevice.readDescriptorForService(
+      serviceUUID,
+      characteristicUUID,
+      descriptorUUID,
+      transactionId
+    );
+    return new DescriptorWrapper(result, this.nitroDevice);
+  }
+
+  async writeDescriptorForService(
+    serviceUUID: UUID,
+    characteristicUUID: UUID,
+    descriptorUUID: UUID,
+    valueBase64: Base64,
+    transactionId?: TransactionId
+  ): Promise<DescriptorWrapper> {
+    const result = await this.nitroDevice.writeDescriptorForService(
+      serviceUUID,
+      characteristicUUID,
+      descriptorUUID,
+      valueBase64,
+      transactionId
+    );
+    return new DescriptorWrapper(result, this.nitroDevice);
+  }
+}
+
+/**
+ * Service wrapper for compatibility
+ */
+export class ServiceWrapper {
+  constructor(
+    private nativeService: NativeService,
+    private nitroDevice: NitroDevice
+  ) {}
+
+  get id(): number {
+    return this.nativeService.id;
+  }
+
+  get uuid(): UUID {
+    return this.nativeService.uuid;
+  }
+
+  get deviceID(): DeviceId {
+    return this.nativeService.deviceID;
+  }
+
+  get isPrimary(): boolean {
+    return this.nativeService.isPrimary;
+  }
+
+  // Delegate to device methods
+  async characteristics(): Promise<CharacteristicWrapper[]> {
+    const device = new DeviceWrapper(this.nitroDevice);
+    return await device.characteristicsForService(this.uuid);
+  }
+
+  async readCharacteristic(
+    characteristicUUID: UUID,
+    transactionId?: TransactionId
+  ): Promise<CharacteristicWrapper> {
+    const device = new DeviceWrapper(this.nitroDevice);
+    return await device.readCharacteristicForService(this.uuid, characteristicUUID, transactionId);
+  }
+
+  // ... other service methods would delegate similarly
+}
+
+/**
+ * Characteristic wrapper for compatibility
+ */
+export class CharacteristicWrapper {
+  constructor(
+    private nativeCharacteristic: NativeCharacteristic,
+    private nitroDevice: NitroDevice
+  ) {}
+
+  get id(): number {
+    return this.nativeCharacteristic.id;
+  }
+
+  get uuid(): UUID {
+    return this.nativeCharacteristic.uuid;
+  }
+
+  get serviceID(): number {
+    return this.nativeCharacteristic.serviceID;
+  }
+
+  get serviceUUID(): UUID {
+    return this.nativeCharacteristic.serviceUUID;
+  }
+
+  get deviceID(): DeviceId {
+    return this.nativeCharacteristic.deviceID;
+  }
+
+  get isReadable(): boolean {
+    return this.nativeCharacteristic.isReadable;
+  }
+
+  get isWritableWithResponse(): boolean {
+    return this.nativeCharacteristic.isWritableWithResponse;
+  }
+
+  get isWritableWithoutResponse(): boolean {
+    return this.nativeCharacteristic.isWritableWithoutResponse;
+  }
+
+  get isNotifiable(): boolean {
+    return this.nativeCharacteristic.isNotifiable;
+  }
+
+  get isNotifying(): boolean {
+    return this.nativeCharacteristic.isNotifying;
+  }
+
+  get isIndicatable(): boolean {
+    return this.nativeCharacteristic.isIndicatable;
+  }
+
+  get value(): Base64 | null {
+    return this.nativeCharacteristic.value;
+  }
+
+  // Delegate to device methods
+  async read(transactionId?: TransactionId): Promise<CharacteristicWrapper> {
+    const device = new DeviceWrapper(this.nitroDevice);
+    return await device.readCharacteristicForService(this.serviceUUID, this.uuid, transactionId);
+  }
+
+  // ... other characteristic methods would delegate similarly
+}
+
+/**
+ * Descriptor wrapper for compatibility
+ */
+export class DescriptorWrapper {
+  constructor(
+    private nativeDescriptor: NativeDescriptor,
+    private nitroDevice: NitroDevice
+  ) {}
+
+  get id(): number {
+    return this.nativeDescriptor.id;
+  }
+
+  get uuid(): UUID {
+    return this.nativeDescriptor.uuid;
+  }
+
+  get characteristicID(): number {
+    return this.nativeDescriptor.characteristicID;
+  }
+
+  get characteristicUUID(): UUID {
+    return this.nativeDescriptor.characteristicUUID;
+  }
+
+  get serviceID(): number {
+    return this.nativeDescriptor.serviceID;
+  }
+
+  get serviceUUID(): UUID {
+    return this.nativeDescriptor.serviceUUID;
+  }
+
+  get deviceID(): DeviceId {
+    return this.nativeDescriptor.deviceID;
+  }
+
+  get value(): Base64 | null {
+    return this.nativeDescriptor.value;
+  }
+
+  // Delegate to device methods
+  async read(transactionId?: TransactionId): Promise<DescriptorWrapper> {
+    const device = new DeviceWrapper(this.nitroDevice);
+    return await device.readDescriptorForService(
+      this.serviceUUID, 
+      this.characteristicUUID, 
+      this.uuid, 
+      transactionId
+    );
+  }
+
+  // ... other descriptor methods would delegate similarly
+}

package/src/compatibility/enums.ts

@@ -0,0 +1,160 @@
+/**
+ * Enum compatibility layer
+ * 
+ * Provides conversion between Nitro's numeric enums and the original 
+ * string-based enums from react-native-ble-plx
+ */
+
+import {
+  State,
+  LogLevel,
+  CharacteristicSubscriptionType,
+  RefreshGattMoment,
+} from '../specs/types';
+
+// String mappings for backward compatibility
+export const StateString = {
+  [State.Unknown]: 'Unknown',
+  [State.Resetting]: 'Resetting',
+  [State.Unsupported]: 'Unsupported',
+  [State.Unauthorized]: 'Unauthorized',
+  [State.PoweredOff]: 'PoweredOff',
+  [State.PoweredOn]: 'PoweredOn',
+} as const;
+
+export const LogLevelString = {
+  [LogLevel.None]: 'None',
+  [LogLevel.Verbose]: 'Verbose',
+  [LogLevel.Debug]: 'Debug',
+  [LogLevel.Info]: 'Info',
+  [LogLevel.Warning]: 'Warning',
+  [LogLevel.Error]: 'Error',
+} as const;
+
+export const CharacteristicSubscriptionTypeString = {
+  [CharacteristicSubscriptionType.Notification]: 'notification',
+  [CharacteristicSubscriptionType.Indication]: 'indication',
+} as const;
+
+export const RefreshGattMomentString = {
+  [RefreshGattMoment.OnConnected]: 'OnConnected',
+} as const;
+
+// Reverse mappings for converting strings back to numeric enums
+const StringToState: { [key: string]: State } = {};
+const StringToLogLevel: { [key: string]: LogLevel } = {};
+const StringToCharacteristicSubscriptionType: { [key: string]: CharacteristicSubscriptionType } = {};
+const StringToRefreshGattMoment: { [key: string]: RefreshGattMoment } = {};
+
+// Build reverse mappings
+Object.entries(StateString).forEach(([num, str]) => {
+  StringToState[str] = parseInt(num) as State;
+});
+
+Object.entries(LogLevelString).forEach(([num, str]) => {
+  StringToLogLevel[str] = parseInt(num) as LogLevel;
+});
+
+Object.entries(CharacteristicSubscriptionTypeString).forEach(([num, str]) => {
+  StringToCharacteristicSubscriptionType[str] = parseInt(num) as CharacteristicSubscriptionType;
+});
+
+Object.entries(RefreshGattMomentString).forEach(([num, str]) => {
+  StringToRefreshGattMoment[str] = parseInt(num) as RefreshGattMoment;
+});
+
+// Conversion functions
+export function stateToString(state: State): string {
+  return StateString[state] ?? 'Unknown';
+}
+
+export function stringToState(stateString: string): State {
+  // Handle case insensitive lookup
+  const lowerString = stateString.toLowerCase();
+  for (const [key, value] of Object.entries(StringToState)) {
+    if (key.toLowerCase() === lowerString) {
+      return value;
+    }
+  }
+  return State.Unknown;
+}
+
+export function logLevelToString(logLevel: LogLevel): string {
+  return LogLevelString[logLevel] ?? 'None';
+}
+
+export function stringToLogLevel(logLevelString: string): LogLevel {
+  // Handle case insensitive lookup
+  const lowerString = logLevelString.toLowerCase();
+  for (const [key, value] of Object.entries(StringToLogLevel)) {
+    if (key.toLowerCase() === lowerString) {
+      return value;
+    }
+  }
+  return LogLevel.None;
+}
+
+export function characteristicSubscriptionTypeToString(
+  type: CharacteristicSubscriptionType
+): string {
+  return CharacteristicSubscriptionTypeString[type] ?? 'notification';
+}
+
+export function stringToCharacteristicSubscriptionType(
+  typeString: string
+): CharacteristicSubscriptionType {
+  // Handle case insensitive lookup
+  const lowerString = typeString.toLowerCase();
+  for (const [key, value] of Object.entries(StringToCharacteristicSubscriptionType)) {
+    if (key.toLowerCase() === lowerString) {
+      return value;
+    }
+  }
+  return CharacteristicSubscriptionType.Notification;
+}
+
+export function refreshGattMomentToString(moment: RefreshGattMoment): 'OnConnected' {
+  return RefreshGattMomentString[moment] as 'OnConnected';
+}
+
+export function stringToRefreshGattMoment(momentString: 'OnConnected'): RefreshGattMoment {
+  return StringToRefreshGattMoment[momentString] ?? RefreshGattMoment.OnConnected;
+}
+
+// Helper function to detect if a value is a string enum vs numeric enum
+export function isStringEnumValue(value: any): boolean {
+  return typeof value === 'string';
+}
+
+// Generic converter that handles both string and numeric enum values
+export function normalizeState(state: State | string): State {
+  if (typeof state === 'string') {
+    return stringToState(state);
+  }
+  return state;
+}
+
+export function normalizeLogLevel(logLevel: LogLevel | string): LogLevel {
+  if (typeof logLevel === 'string') {
+    return stringToLogLevel(logLevel);
+  }
+  return logLevel;
+}
+
+export function normalizeCharacteristicSubscriptionType(
+  type: CharacteristicSubscriptionType | 'notification' | 'indication'
+): CharacteristicSubscriptionType {
+  if (typeof type === 'string') {
+    return stringToCharacteristicSubscriptionType(type);
+  }
+  return type;
+}
+
+export function normalizeRefreshGattMoment(
+  moment: RefreshGattMoment | 'OnConnected'
+): RefreshGattMoment {
+  if (typeof moment === 'string') {
+    return stringToRefreshGattMoment(moment);
+  }
+  return moment;
+}

package/src/compatibility/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Compatibility layer for react-native-ble-nitro
+ * 
+ * This module provides compatibility shims and converters to maintain 
+ * 100% API compatibility with react-native-ble-plx while working with 
+ * Nitro's type system constraints.
+ */
+
+export * from './serviceData';
+export * from './deviceWrapper';
+export * from './constants';
+
+// Explicitly export enum utilities to avoid conflicts
+export {
+  stateToString,
+  stringToState,
+  logLevelToString,
+  stringToLogLevel,
+  characteristicSubscriptionTypeToString,
+  stringToCharacteristicSubscriptionType,
+  normalizeState,
+  normalizeLogLevel,
+  normalizeCharacteristicSubscriptionType,
+} from './enums';

package/src/compatibility/serviceData.ts

@@ -0,0 +1,85 @@
+/**
+ * Service Data compatibility layer
+ * 
+ * Provides conversion between Nitro's structured ServiceDataEntry[] format
+ * and the original { [uuid: string]: Base64 } format from react-native-ble-plx
+ */
+
+import type { ServiceDataEntry, UUID, Base64 } from '../specs/types';
+
+/**
+ * Convert ServiceDataEntry array to the original index signature format
+ */
+export function serviceDataArrayToMap(entries: ServiceDataEntry[] | null): { [uuid: string]: Base64 } | null {
+  if (!entries || entries.length === 0) {
+    return null;
+  }
+
+  const result: { [uuid: string]: Base64 } = {};
+  entries.forEach(entry => {
+    result[entry.uuid] = entry.data;
+  });
+  return result;
+}
+
+/**
+ * Convert the original index signature format to ServiceDataEntry array
+ */
+export function serviceDataMapToArray(map: { [uuid: string]: Base64 } | null): ServiceDataEntry[] | null {
+  if (!map || Object.keys(map).length === 0) {
+    return null;
+  }
+
+  return Object.entries(map).map(([uuid, data]) => ({
+    uuid: uuid as UUID,
+    data,
+  }));
+}
+
+/**
+ * Merge two service data maps (used in device updates)
+ */
+export function mergeServiceDataMaps(
+  existing: { [uuid: string]: Base64 } | null,
+  updates: { [uuid: string]: Base64 } | null
+): { [uuid: string]: Base64 } | null {
+  if (!existing && !updates) return null;
+  if (!existing) return updates;
+  if (!updates) return existing;
+
+  return { ...existing, ...updates };
+}
+
+/**
+ * Merge two service data arrays (used in native updates)
+ */
+export function mergeServiceDataArrays(
+  existing: ServiceDataEntry[] | null,
+  updates: ServiceDataEntry[] | null
+): ServiceDataEntry[] | null {
+  const existingMap = serviceDataArrayToMap(existing);
+  const updatesMap = serviceDataArrayToMap(updates);
+  const mergedMap = mergeServiceDataMaps(existingMap, updatesMap);
+  return serviceDataMapToArray(mergedMap);
+}
+
+/**
+ * Check if service data contains a specific service UUID
+ */
+export function hasServiceUUID(serviceData: { [uuid: string]: Base64 } | null, uuid: UUID): boolean {
+  return serviceData ? uuid in serviceData : false;
+}
+
+/**
+ * Get service data for a specific UUID
+ */
+export function getServiceData(serviceData: { [uuid: string]: Base64 } | null, uuid: UUID): Base64 | null {
+  return serviceData?.[uuid] || null;
+}
+
+/**
+ * Get all service UUIDs from service data
+ */
+export function getServiceUUIDs(serviceData: { [uuid: string]: Base64 } | null): UUID[] {
+  return serviceData ? Object.keys(serviceData) as UUID[] : [];
+}