@maccesar/titools 2.10.1 → 3.2.0

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

@@ -1,150 +0,0 @@
-# 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

@@ -1,279 +0,0 @@
-# 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

@@ -1,99 +0,0 @@
-# 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).