0
# TNS Platform Declarations
1

2
TNS Platform Declarations is a TypeScript declarations library that provides platform-specific type definitions for NativeScript applications. It enables developers to access native Android and iOS APIs with full type safety, offering comprehensive TypeScript declarations for multiple Android API levels (17-29) and complete iOS SDK frameworks.
3

4
## Package Information
5

6
- **Package Name**: tns-platform-declarations
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install tns-platform-declarations`
10

11
## Core Imports
12

13
### Basic Platform Access
14

15
```typescript
16
/// <reference path="./node_modules/tns-platform-declarations/android.d.ts" />
17
/// <reference path="./node_modules/tns-platform-declarations/ios.d.ts" />
18
```
19

20
### API Level Specific (Android)
21

22
```typescript
23
// For higher Android API levels
24
/// <reference path="./node_modules/tns-platform-declarations/android-24.d.ts" />
25
/// <reference path="./node_modules/tns-platform-declarations/android-29.d.ts" />
26
```
27

28
## Basic Usage
29

30
```typescript
31
/// <reference path="./node_modules/tns-platform-declarations/android.d.ts" />
32
/// <reference path="./node_modules/tns-platform-declarations/ios.d.ts" />
33

34
// Android usage
35
const permission = android.Manifest.permission.ACCESS_FINE_LOCATION;
36
const javaObject = new java.lang.Object();
37
const floatValue = float(3.14);
38

39
// iOS usage  
40
const nsObject = new NSObject();
41
const pointer = new interop.Pointer();
42
const reference = new interop.Reference<number>(42);
43

44
// Memory management
45
__releaseNativeCounterpart(javaObject);
46
__releaseNativeCounterpart(nsObject);
47
```
48

49
## Architecture
50

51
TNS Platform Declarations is organized around platform separation and version support:
52

53
- **Platform Entry Points**: Separate entry points for Android (`android.d.ts`) and iOS (`ios.d.ts`) platforms
54
- **Version Support**: Multiple Android API level variants (17-29) with corresponding AndroidX support
55
- **Framework Coverage**: Complete iOS SDK framework declarations (139 frameworks)
56
- **Memory Management**: Built-in functions for native object lifecycle management
57
- **Type Safety**: Full TypeScript definitions ensuring compile-time type checking
58
- **Interoperability**: Rich interop layer for seamless native code integration
59

60
## Capabilities
61

62
### Android Platform API
63

64
Comprehensive Android SDK type definitions with support for multiple API levels and AndroidX libraries. Includes native object access, memory management, and NativeScript-specific widgets.
65

66
```typescript { .api }
67
// Main entry point - defaults to API level 17
68
/// <reference path="./android.d.ts" />
69

70
// API level specific variants
71
/// <reference path="./android-17.d.ts" />
72
/// <reference path="./android-18.d.ts" />
73
// ... through android-29.d.ts
74

75
// Core Android functions
76
declare function float(num: number): any;
77
declare function long(num: number): any;
78
declare var gc: () => void;
79
declare function __releaseNativeCounterpart(object: java.lang.Object): void;
80
```
81

82
[Android Platform](./android-platform.md)
83

84
### iOS Platform API
85

86
Complete iOS SDK framework declarations with native interoperability layer. Provides access to all iOS frameworks, memory management utilities, and Objective-C runtime integration.
87

88
```typescript { .api }
89
// Main entry point
90
/// <reference path="./ios.d.ts" />
91

92
// Core iOS functions
93
declare function __collect(): void;
94
declare function __releaseNativeCounterpart(object: NSObject): void;
95
declare function __time(): Number;
96
```
97

98
[iOS Platform](./ios-platform.md)
99

100
### Native Interoperability
101

102
Advanced native code integration layer providing pointer arithmetic, memory management, type conversion, and native function calls for iOS platform.
103

104
```typescript { .api }
105
declare module interop {
106
  interface Pointer {
107
    new(offset: number);
108
    add(offset: number): Pointer;
109
    subtract(offset: number): Pointer;
110
    toNumber(): number;
111
  }
112
  
113
  interface Reference<T> {
114
    value: T;
115
  }
116
  
117
  function alloc(size: number): AdoptedPointer;
118
  function free(ptr: Pointer): void;
119
  function sizeof(type: any): number;
120
}
121
```
122

123
[Native Interoperability](./native-interop.md)
124

125
### NativeScript Widgets
126

127
Platform-specific NativeScript widget declarations for Android development, including async utilities for HTTP, file operations, and image processing.
128

129
```typescript { .api }
130
declare module org.nativescript.widgets {
131
  export class CustomTransition extends androidx.transition.Visibility {
132
    constructor(animatorSet: android.animation.AnimatorSet, transitionName: string);
133
    setResetOnTransitionEnd(resetOnTransitionEnd: boolean): void;
134
    getTransitionName(): string;
135
  }
136
}
137
```
138

139
[NativeScript Widgets](./nativescript-widgets.md)
140

141
## Types
142

143
### Common Types
144

145
```typescript { .api }
146
interface ArrayConstructor {
147
  create(type: any, count: number): any;
148
}
149

150
declare module native {
151
  export class Array<T> {
152
    constructor();
153
    length: number;
154
    [index: number]: T;
155
  }
156
}
157
```
158

159
## Configuration
160

161
### TypeScript Configuration
162

163
Recommended `tsconfig.json` settings for using TNS Platform Declarations:
164

165
```json
166
{
167
  "compilerOptions": {
168
    "module": "commonjs",
169
    "target": "es5",
170
    "experimentalDecorators": true,
171
    "skipLibCheck": true,
172
    "lib": ["es6", "dom"]
173
  }
174
}
175
```
176

177
### Reference Setup
178

179
Create a `reference.d.ts` file in your project:
180

181
```typescript
182
/// <reference path="./node_modules/tns-platform-declarations/ios.d.ts" />
183
/// <reference path="./node_modules/tns-platform-declarations/android.d.ts" />
184
```
185

186
## Performance Considerations
187

188
- **Memory Usage**: Declaration files are large and memory-intensive
189
- **CPU Impact**: Compilation can be CPU intensive with all declarations
190
- **Build Optimization**: Consider using `skipLibCheck: true` in TypeScript configuration
191
- **API Level Selection**: Use specific Android API levels instead of default to reduce overhead