@maccesar/titools 3.2.0 → 4.0.0

package/skills/ti-guides/references/coding-best-practices.md

@@ -0,0 +1,150 @@
+# Coding best practices
+
+Titanium apps are easiest to maintain when they use a single-context, modular pattern with clear structure and organized resources.
+
+## 1. Scope management
+
+- Avoid global scope. Global variables are not automatically garbage collected and can create naming conflicts.
+- Always use `let` or `const`. The original guide uses `var`, but modern code should not. Omitting declarations places variables in global scope.
+
+## 2. Memory leak prevention
+
+- Listeners on `Ti.App`, `Ti.Geolocation`, and similar globals can leak memory if they reference local objects and are not removed.
+```javascript
+// Anti-pattern
+Ti.App.addEventListener('data:sync', (e) => {
+  localView.text = e.text // localView is now leaked
+})
+```
+- Rule: global events should only handle global objects. Always `removeEventListener` during cleanup.
+
+## 3. Event naming conventions
+
+- Do not use spaces in event names. Spaces can cause issues with Backbone.js and other libraries that split event names on spaces.
+```javascript
+// Wrong - may fire multiple times
+Ti.App.fireEvent('my event')
+
+// Correct - use colon or underscore
+Ti.App.fireEvent('my:event')
+Ti.App.fireEvent('my_event')
+```
+
+## 4. Performance
+
+- Defer script loading. Only `require` modules when you need them.
+
+Defer loading to reduce startup time. Only `require` modules when you need them.
+
+Lazy script loading example:
+```javascript
+// must be loaded at launch
+const WindowOne = require('ui/WindowOne').WindowOne;
+const win1 = new WindowOne();
+win1.open();
+
+win1.addEventListener('click', () => {
+  // load window two JavaScript only when needed
+  const WindowTwo = require('ui/WindowTwo').WindowTwo;
+  const win2 = new WindowTwo();
+  win2.open();
+
+  win2.addEventListener('click', () => {
+    // load window three JavaScript only when needed
+    const WindowThree = require('ui/WindowThree').WindowThree;
+    const win3 = new WindowThree();
+    win3.open();
+  });
+});
+```
+
+- Bridge efficiency: minimize requests for device properties like `Ti.Platform.osname`. Store them in a local variable:
+```javascript
+const isAndroid = (Ti.Platform.osname === 'android')
+if (isAndroid) { /* Android path */ } else { /* iOS path */ }
+```
+- Avoid extending the `Ti` namespace. Three reasons:
+  1. Ti objects are proxies to native OS components — your extensions may conflict with native functionality.
+  2. Arrays stored on the namespace may be immutable; objects may be null unexpectedly.
+  3. There is no guarantee properties persist across SDK versions.
+  Use your own namespace or CommonJS module instead of modifying `Ti`.
+
+## 5. App architecture recommendations
+
+### Modular components with CommonJS (recommended)
+
+Titanium's primary recommended architecture. It uses discrete modules and avoids globals. See `commonjs-advanced.md` for module patterns and path resolution.
+
+MyModule.js:
+```javascript
+// Private variable
+const defaultMessage = "Hello world";
+
+exports.sayHello = (msg) => {
+  Ti.API.info('Hello ' + msg);
+};
+
+exports.helloWorld = () => {
+  Ti.API.info(defaultMessage);
+}
+```
+
+app.js:
+```javascript
+const myModule = require('/MyModule');
+myModule.sayHello('User');
+```
+
+### Namespace with deferred loading (alternative pattern)
+
+If not using CommonJS, you can still defer loading with a namespace:
+
+```javascript
+const someNameSpace = () => {
+  const API = {
+    init() {
+      // create UI or initialize
+    },
+    reset() {
+      // null objects, clean up
+    }
+  }
+  return API
+}
+const ns = new someNameSpace()
+```
+
+### Custom objects as components
+
+Popular for rapid deployment. It uses a namespace hierarchy. This pattern is less efficient than CommonJS modules, and object references can persist after they are no longer needed.
+
+```javascript
+const myapp = {};
+(() => {
+  myapp.ui = {};
+  myapp.ui.createApplicationWindow = () => {
+    const win = Ti.UI.createWindow({ backgroundColor:'white' });
+    return win;
+  };
+})();
+```
+
+### Classical-based patterns
+
+Not recommended. JavaScript is not class-based in the same way, and this approach adds overhead during rapid prototyping.
+
+## 6. Security best practices
+
+- Do not store sensitive data in non-JS files. JavaScript files are minified and obfuscated, but images, JSON, SQLite databases, and other non-JS files are packaged as-is. APK and IPA files are ZIP files that can be extracted.
+```javascript
+// Wrong - API keys visible in app/assets/config.json
+const config = require('assets/config.json')
+
+// Correct - store in code or use secure storage
+const API_KEY = Ti.App.Properties.getString('api_key')
+```
+
+## 7. Multiplatform strategies
+
+- Code branching: use for small differences.
+- Platform files: use `.ios.js` or `.android.js` for major logic differences so code stays readable.

package/skills/ti-guides/references/commonjs-advanced.md

@@ -0,0 +1,279 @@
+# CommonJS advanced patterns
+
+For more on CommonJS in Titanium, see the official CommonJS Modules guide in the Titanium SDK documentation.
+
+## Definitions
+
+- Module: any CommonJS-compliant module used in a Titanium SDK application. This can be a JavaScript file bundled with the app or a native extension that exposes a JavaScript API.
+- Resources: the Resources directory of a Titanium application, where source code lives before the build system processes it. In Alloy, CommonJS modules live in `app/lib`.
+- `exports`: a free variable within a module. Add properties to expose a public API.
+- `module.exports`: an object you can replace to define the module's public API.
+
+## 1. Stateful modules (singleton pattern)
+
+Modules in Titanium are created once per JavaScript context and reused on subsequent `require()` calls. This makes them useful for shared state.
+
+### Example: stateful counter module
+
+```javascript
+// app/lib/counter.js
+let _count = 0
+
+exports.increment = () => {
+  _count++
+}
+
+exports.getCount = () => {
+  return _count
+}
+
+exports.reset = () => {
+  _count = 0
+}
+```
+
+Usage: multiple controllers that require this module share the same `_count` state.
+
+A module is created once per Titanium JavaScript context. Additional contexts create new module instances.
+
+## 2. Native/compiled modules
+
+When `require()` is called, Titanium checks for a native/compiled module before it looks for a JavaScript module. Native modules take priority.
+
+Native modules are identified by a single string and configured in `tiapp.xml`:
+
+```xml
+<modules>
+  <module version="1.0">ti.paypal</module>
+</modules>
+```
+
+```javascript
+const paypal = require('ti.paypal')
+```
+
+Titanium loads `ti.paypal` as a native module and will not look for a JavaScript file in Resources. If no native module matches, it falls back to JavaScript module resolution.
+
+## 3. Module path resolution
+
+The string passed to `require()` is treated as a path to a JavaScript file, without the `.js` extension.
+
+Resolution rules:
+- No prefix (`require('app/lib/myModule')`): resolved relative to the `Resources` directory (or `app/lib` in Alloy)
+- `/` prefix (`require('/app/lib/myModule')`): also resolved relative to the `Resources` directory
+- `./` or `../` prefix (`require('./widgets/SomeView')`): resolved relative to the current module file
+
+Example with relative paths:
+
+Given these files:
+- `Resources/app/ui/SomeCustomView.js`
+- `Resources/app/ui/widgets/SomeOtherCustomView.js`
+- `Resources/app/lib/myModule.js`
+
+Inside `SomeCustomView.js`:
+```javascript
+const myModule = require('../lib/myModule')
+const SomeOtherCustomView = require('./widgets/SomeOtherCustomView')
+```
+
+The `.js` extension is omitted in `require()` calls.
+
+## 4. Caching behavior
+
+Titanium caches the object returned by `require()` and returns the same reference without re-evaluating the code.
+
+If you need code evaluated multiple times, export a function that creates what you need instead.
+
+```javascript
+// Good: factory pattern
+exports.createView = (args) => {
+  return Ti.UI.createView(args)
+}
+
+// Bad: expecting re-evaluation
+```
+
+## 5. ES6+ support (SDK 7.1.0+)
+
+Since Titanium SDK 7.1.0, you can use ES6+ module syntax. Code is transpiled to ES5 for all platforms.
+
+```javascript
+// MyClass.js
+export default class MyClass {
+  constructor(name) {
+    this.name = name
+  }
+
+  greet() {
+    return `Hello, ${this.name}`
+  }
+}
+
+// Usage in controller
+import MyClass from 'MyClass'
+const instance = new MyClass('World')
+```
+
+## 6. Module composition patterns
+
+### Exports object pattern
+
+```javascript
+exports.sayHello = (name) => {
+  Ti.API.info(`Hello ${name}`)
+}
+
+exports.version = 1.4
+```
+
+### Constructor pattern (`module.exports`)
+
+```javascript
+class Person {
+  constructor(firstName, lastName) {
+    this.firstName = firstName
+    this.lastName = lastName
+  }
+
+  fullName() {
+    return `${this.firstName} ${this.lastName}`
+  }
+}
+
+module.exports = Person
+```
+
+### Utility library pattern
+
+```javascript
+// app/lib/logger.js
+exports.info = (str) => {
+  Ti.API.info(`${new Date()}: ${str}`)
+}
+
+exports.debug = (str) => {
+  Ti.API.debug(`${new Date()}: ${str}`)
+}
+```
+
+Usage:
+```javascript
+const logger = require('logger')
+logger.info('some log statement with a timestamp')
+```
+
+## 7. Packages of related functionality
+
+Group related classes or helpers in a single module:
+
+```javascript
+// app/lib/geo.js
+class Point {
+  constructor(x, y) {
+    this.x = x
+    this.y = y
+  }
+}
+
+class Line {
+  constructor(start, end) {
+    this.start = start
+    this.end = end
+  }
+
+  slope() {
+    return (this.end.y - this.start.y) / (this.end.x - this.start.x)
+  }
+
+  yIntercept() {
+    return this.start.y - (this.slope() * this.start.x)
+  }
+}
+
+exports.Point = Point
+exports.Line = Line
+```
+
+Usage:
+```javascript
+const Geo = require('lib/geo')
+
+const start = new Geo.Point(1, -5)
+const end = new Geo.Point(10, 2)
+const line = new Geo.Line(start, end)
+Ti.API.info(line.slope())
+```
+
+## 8. Inter-module state sharing
+
+When a module assigns a primitive value to `exports`, the consumer gets a copy, not a live reference. Changes to the internal variable are not reflected in the exported property.
+
+```javascript
+// app/lib/statefulModule.js
+let _stepVal = 5
+
+exports.setPointStep = (value) => {
+  _stepVal = value
+}
+
+exports.getPointStep = () => {
+  return _stepVal
+}
+
+exports.stepVal = _stepVal // This is a copy of _stepVal (value: 5)
+```
+
+```javascript
+const stateful = require('statefulModule')
+stateful.setPointStep(10)
+Ti.API.info(stateful.getPointStep()) // 10 - correct, uses getter
+Ti.API.info(stateful.stepVal)        // 5  - still the original copy
+```
+
+Rule: use getter/setter functions for stateful values. Direct property exports of primitives are snapshots at module load time.
+
+## 9. Antipatterns to avoid
+
+### Do not assign directly to `exports`
+
+```javascript
+// Wrong
+function Person() {}
+exports = Person
+
+// Correct
+module.exports = Person
+```
+
+### Do not mix `module.exports` and `exports.*`
+
+```javascript
+// Discouraged
+module.exports = Person
+exports.foo = 'bar'
+
+// Use one consistently
+```
+
+### Avoid globals across modules
+
+Any data a module needs should be passed during construction or initialization. Avoid globals shared across modules.
+
+## 10. Security and scope
+
+All modules have private scope. Variables declared within the module are private unless added to `exports`.
+
+```javascript
+const _privateVar = 'secret' // Not accessible outside
+
+exports.publicMethod = () => {
+  // Can access _privateVar
+  return _privateVar
+}
+```
+
+## 11. Node.js compatibility
+
+Titanium supports Node.js module patterns and `require()` resolution. Node.js modules can often be used directly.
+
+For details, refer to the official Titanium Node.js guide.

package/skills/ti-guides/references/hello-world.md

@@ -0,0 +1,99 @@
+# Hello world: project creation
+
+Quick guide to creating your first Titanium project.
+
+## Creating a new project
+
+### Using CLI
+
+```bash
+ti create -t app --id <APP_ID> -n <APP_NAME> -p <PLATFORMS> -d <WORKSPACE>
+```
+
+Example:
+```bash
+ti create -t app --id com.example.hello -n HelloWorld -p android,ios -d ~/Projects
+```
+
+### Using VS Code
+
+VS Code with the Titanium extension supports project creation via the command palette. The CLI is the most reliable method and works in any editor.
+
+## Project fields
+
+| Field              | Description             | Rules                      |
+| ------------------ | ----------------------- | -------------------------- |
+| Project name       | App name shown to users | -                          |
+| App ID             | Reverse domain notation | `com.company.appname`      |
+| Company URL        | Your website            | -                          |
+| SDK Version        | Titanium SDK to use     | Use latest                 |
+| Deployment Targets | Platforms to support    | android, ios, ipad, iphone |
+
+### App ID naming guidelines
+
+- Use Java package style: `com.yourdomain.yourappname`
+- No spaces or special characters
+- All lowercase (Android issues with uppercase)
+- No Java keywords (`case`, `package`, etc.)
+- Cannot change after publishing
+- On iOS, the App ID must match the Bundle Identifier. On Android, it becomes the Application Package Name.
+
+## Project structure
+
+```
+MyApp/
+├── app/                    # Alloy app source
+│   ├── assets/            # Images, fonts
+│   ├── controllers/       # JS controllers
+│   ├── models/           # Backbone models
+│   ├── views/            # XML views
+│   └── styles/           # TSS styles
+├── platform/              # Platform-specific files
+│   ├── android/
+│   └── ios/
+├── Resources/             # Code files and graphics with platform-specific subdirectories
+│   ├── android/          # Android-specific assets
+│   └── iphone/           # iOS-specific assets
+├── i18n/                  # Internationalization
+├── tiapp.xml             # App configuration
+├── config.json           # Alloy config
+└── app.js                # Bootstrap file loaded first when app launches
+```
+
+## Running your app
+
+### iOS simulator
+```bash
+ti build -p ios -C "iPhone 15"
+```
+
+### Android emulator
+```bash
+ti build -p android -C "Pixel_4_API_34"
+```
+
+### Physical device
+```bash
+ti build -p ios -T device
+ti build -p android -T device
+```
+
+## Simulator vs emulator
+
+- iOS simulator: simulates the environment within an iOS device. It is a macOS executable that runs your cross-compiled code.
+- Android emulator: provides a virtual hardware environment that runs the Android OS and platform components.
+
+Neither environment is a perfect representation of a physical device. Always test on real hardware before publishing.
+
+## How Titanium works (under the covers)
+
+1. Pre-compile: JavaScript is minified and statically analyzed to build a dependency hierarchy of Titanium APIs used.
+2. Stub generation: a front-end compiler creates native stub files, native project files, and platform-specific code needed for compilation.
+3. Native build: Titanium calls platform-specific compilers (for example, `xcodebuild` for iOS and Gradle for Android) to build the native app.
+4. Encryption: JavaScript code is encrypted when building for production (release) or for device. Original code is not retrievable in human-readable form.
+
+## Best practices
+
+1. Test on physical devices. The simulator/emulator is not a perfect proxy.
+2. Use Alloy for new projects for better structure and maintainability.
+3. Keep the App ID consistent. Match Bundle ID (iOS) and Package ID (Android).