@maccesar/titools 2.2.3 → 2.2.8

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

@@ -1,36 +1,40 @@
-# Coding Best Practices
+# Coding best practices
 
-The recommended standard for Titanium apps is a single-context, modular pattern with well-structured code and well-organized resources.
+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 cause naming conflicts.
-- **Always use `let` or `const`**: (Original guide says `var`, but modernization rules apply). Omitting declarations places variables in the global scope.
+## 1. Scope management
 
-## 2. Memory Leak Prevention
-- **Global Event Listeners**: Listeners on `Ti.App`, `Ti.Geolocation`, etc., will leak memory if they reference locally scoped objects unless explicitly removed.
+- 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
+// 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.
+- Rule: global events should only handle global objects. Always `removeEventListener` during cleanup.
+
+## 3. Event naming conventions
 
-## 3. Event Naming Conventions
-- **No Spaces in Event Names**: Using spaces in custom event names causes issues with Backbone.js and other libraries that use spaces as delimiters.
+- 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
+// Wrong - may fire multiple times
 Ti.App.fireEvent('my event')
 
-// ✅ CORRECT - use colon or underscore
+// Correct - use colon or underscore
 Ti.App.fireEvent('my:event')
 Ti.App.fireEvent('my_event')
 ```
 
 ## 4. Performance
-- **Defer Script Loading**: Evaluate JavaScript only when needed. Don't `require` modules at startup if they are only for specific screens.
 
-**Lazy script loading example:**
+- Defer script loading. Only `require` modules when you need them.
+
+Lazy script loading example:
 ```javascript
 // must be loaded at launch
 const WindowOne = require('ui/WindowOne').WindowOne;
@@ -52,15 +56,16 @@ win1.addEventListener('click', () => {
 });
 ```
 
-- **Bridge Efficiency**: Minimize requests for device properties like `Ti.Platform.osname`. Store them in a local variable once.
-- **Avoid Extending Ti Namespace**: Ti namespace objects are proxy representations of native OS components. Properties set on them may be stored on the proxy but won't be passed to the native object. Arrays stored on proxies return copies, not live references. There is no guarantee properties will persist across SDK versions. Use native modules instead to extend core functionality.
+- Bridge efficiency: minimize requests for device properties like `Ti.Platform.osname`. Store them in a local variable.
+- Avoid extending the `Ti` namespace. `Ti` objects are proxies to native components. Properties set on them may not reach the native object, arrays return copies, and persistence across SDK versions is not guaranteed. Use modules instead.
+
+## 5. App architecture recommendations
 
-## 5. App Architecture Recommendations
+### Modular components with CommonJS (recommended)
 
-### Modular Components with CommonJS (Recommended)
-Titanium's primary recommended architecture. Discrete and independent building blocks that eliminate global variables. See `commonjs-advanced.md` for detailed module patterns and path resolution.
+Titanium's primary recommended architecture. It uses discrete modules and avoids globals. See `commonjs-advanced.md` for module patterns and path resolution.
 
-**MyModule.js**
+MyModule.js:
 ```javascript
 // Private variable
 const defaultMessage = "Hello world";
@@ -74,14 +79,15 @@ exports.helloWorld = () => {
 }
 ```
 
-**app.js**
+app.js:
 ```javascript
 const myModule = require('/MyModule');
 myModule.sayHello('User');
 ```
 
-### Custom Objects as Components
-Popular for rapid deployment. Uses a namespace hierarchy. However, this pattern is less performant than CommonJS modules. Memory management can be difficult as object references may persist after they're no longer needed.
+### 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 = {};
@@ -94,19 +100,22 @@ const myapp = {};
 })();
 ```
 
-### Classical-based Patterns
-Not recommended as JavaScript is not a class-based language. It confuses classes and objects and is slower to implement in rapid prototyping.
+### 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
-- **No Sensitive Data in Non-JS Files**: JavaScript files are minified and obfuscated during build, but images, JSON files, SQLite databases, and other non-.js files are packaged as-is. APK and IPA files are essentially ZIP files that can be extracted.
+## 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
+// Wrong - API keys visible in app/assets/config.json
 const config = require('assets/config.json')
 
-// ✅ CORRECT - Store in code or use secure storage
+// 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 to keep code readable.
+## 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,19 +1,20 @@
-# CommonJS Advanced Patterns
+# CommonJS advanced patterns
 
-> For more on CommonJS in Titanium, see the official CommonJS Modules guide in the Titanium SDK documentation.
+For more on CommonJS in Titanium, see the official CommonJS Modules guide in the Titanium SDK documentation.
 
 ## Definitions
 
-- **Module** - Any CommonJS-compliant module consumed in a Titanium SDK application. This can be a JavaScript file included with the app, or a native extension to Titanium which exposes a JavaScript API.
-- **Resources** - The Resources directory of a Titanium application, where user source code lives before processing by the build system. **Note**: For Alloy, CommonJS modules are placed in `app/lib`.
-- **`exports`** - A free variable within a module, to which multiple properties may be added to create a public interface.
-- **`module.exports`** - An object within a module, which may be REPLACED by an object representing the public interface to the module.
+- 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)
+## 1. Stateful modules (singleton pattern)
 
-Modules in Titanium are created once per JavaScript context and then passed by reference on subsequent `require()` calls. This makes them ideal for maintaining application state.
+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
 
-### Example: Stateful Counter Module
 ```javascript
 // app/lib/counter.js
 let _count = 0
@@ -31,14 +32,13 @@ exports.reset = () => {
 }
 ```
 
-**Usage**: Multiple controllers requiring this module share the same `_count` state.
+Usage: multiple controllers that require this module share the same `_count` state.
 
-### Critical Note
-A module is created once **per Titanium JavaScript context**. Additional contexts create new module instances.
+A module is created once per Titanium JavaScript context. Additional contexts create new module instances.
 
-## 2. Native/Compiled Modules
+## 2. Native/compiled modules
 
-When `require()` is called, Titanium first checks for a native/compiled module before looking for a JavaScript module. Native modules take priority.
+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`:
 
@@ -52,18 +52,18 @@ Native modules are identified by a single string and configured in `tiapp.xml`:
 const paypal = require('ti.paypal')
 ```
 
-Titanium loads `ti.paypal` as a native module and will NOT look for a JavaScript file in Resources. Only if no native module matches does Titanium fall back to JavaScript module resolution.
+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
+## 3. Module path resolution
 
-The string passed to `require()` is treated as a path to a JavaScript file, minus the `.js` extension.
+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
+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:**
+Example with relative paths:
 
 Given these files:
 - `Resources/app/ui/SomeCustomView.js`
@@ -76,24 +76,24 @@ const myModule = require('../lib/myModule')
 const SomeOtherCustomView = require('./widgets/SomeOtherCustomView')
 ```
 
-The `.js` extension is always omitted in `require()` calls.
+The `.js` extension is omitted in `require()` calls.
 
-## 4. Caching Behavior
+## 4. Caching behavior
 
-Titanium caches the object returned by `require()` and provides the same reference without re-evaluating the code.
+Titanium caches the object returned by `require()` and returns the same reference without re-evaluating the code.
 
-**Implication**: If you think you need code evaluated multiple times, create a module with a callable function instead.
+If you need code evaluated multiple times, export a function that creates what you need instead.
 
 ```javascript
-// Good - factory pattern
+// Good: factory pattern
 exports.createView = (args) => {
   return Ti.UI.createView(args)
 }
 
-// Bad - expecting re-evaluation
+// Bad: expecting re-evaluation
 ```
 
-## 5. ES6+ Support (SDK 7.1.0+)
+## 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.
 
@@ -114,9 +114,10 @@ import MyClass from 'MyClass'
 const instance = new MyClass('World')
 ```
 
-## 6. Module Composition Patterns
+## 6. Module composition patterns
+
+### Exports object pattern
 
-### Exports Object Pattern
 ```javascript
 exports.sayHello = (name) => {
   Ti.API.info(`Hello ${name}`)
@@ -125,7 +126,8 @@ exports.sayHello = (name) => {
 exports.version = 1.4
 ```
 
-### Constructor Pattern (module.exports)
+### Constructor pattern (`module.exports`)
+
 ```javascript
 class Person {
   constructor(firstName, lastName) {
@@ -141,7 +143,8 @@ class Person {
 module.exports = Person
 ```
 
-### Utility Library Pattern
+### Utility library pattern
+
 ```javascript
 // app/lib/logger.js
 exports.info = (str) => {
@@ -153,15 +156,15 @@ exports.debug = (str) => {
 }
 ```
 
-**Usage:**
+Usage:
 ```javascript
 const logger = require('logger')
 logger.info('some log statement with a timestamp')
 ```
 
-## 7. Inter-Module State Sharing
+## 7. Inter-module state sharing
 
-When a module assigns a primitive value to `exports`, the consumer gets a **copy**, not a live reference. Subsequent changes to the internal variable are NOT reflected in the exported property.
+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
@@ -175,43 +178,46 @@ exports.getPointStep = () => {
   return _stepVal
 }
 
-exports.stepVal = _stepVal // This is a COPY of _stepVal (value: 5)
+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!
+Ti.API.info(stateful.stepVal)        // 5  - still the original copy
 ```
 
-**Rule**: Always use getter/setter functions for stateful values. Direct property exports of primitives are snapshots at module load time.
+Rule: use getter/setter functions for stateful values. Direct property exports of primitives are snapshots at module load time.
 
-## 8. Antipatterns to Avoid
+## 8. Antipatterns to avoid
+
+### Do not assign directly to `exports`
 
-### Don't Assign Directly to exports
 ```javascript
-// ❌ WRONG - won't work
+// Wrong
 function Person() {}
 exports = Person
 
-// ✅ CORRECT
+// Correct
 module.exports = Person
 ```
 
-### Don't Mix module.exports and exports.*
+### Do not mix `module.exports` and `exports.*`
+
 ```javascript
-// ❌ DISCOURAGED
+// Discouraged
 module.exports = Person
 exports.foo = 'bar'
 
-// ✅ Use one consistently
+// Use one consistently
 ```
 
-### No Global Variables Across Modules
-Any data a module needs must be passed during construction or initialization. Never rely on globals shared across modules.
+### Avoid globals across modules
+
+Any data a module needs should be passed during construction or initialization. Avoid globals shared across modules.
 
-## 9. Security and Scope
+## 9. Security and scope
 
 All modules have private scope. Variables declared within the module are private unless added to `exports`.
 
@@ -224,8 +230,8 @@ exports.publicMethod = () => {
 }
 ```
 
-## 10. Node.js Compatibility
+## 10. Node.js compatibility
 
 Titanium supports Node.js module patterns and `require()` resolution. Node.js modules can often be used directly.
 
-For detailed Node.js support information, refer to the official Titanium Node.js guide.
+For details, refer to the official Titanium Node.js guide.

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

@@ -1,8 +1,8 @@
-# Hello World - Project Creation
+# Hello world: project creation
 
 Quick guide to creating your first Titanium project.
 
-## Creating a New Project
+## Creating a new project
 
 ### Using CLI
 
@@ -10,39 +10,39 @@ Quick guide to creating your first Titanium project.
 ti create -t app --id <APP_ID> -n <APP_NAME> -p <PLATFORMS> -d <WORKSPACE>
 ```
 
-**Example:**
+Example:
 ```bash
 ti create -t app --id com.example.hello -n HelloWorld -p android,ios -d ~/Projects
 ```
 
 ### Using Studio/VS Code
 
-**File** > **New** > **Mobile App Project**
+File > New > Mobile App Project
 
-Choose template:
-- **Alloy** - MVC framework (recommended)
-- **Classic** - No framework
+Choose a template:
+- Alloy: MVC framework (recommended)
+- Classic: no framework
 
-## Project Fields
+## 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 |
+| 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
+### App ID naming guidelines
 
-- Use Java Package Name style: `com.yourdomain.yourappname`
+- 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
-- **Platform Relationship**: On iOS, the App ID must match the Bundle Identifier; on Android, it serves as the Application Package Name
+- On iOS, the App ID must match the Bundle Identifier. On Android, it becomes the Application Package Name.
 
-## Project Structure
+## Project structure
 
 ```
 MyApp/
@@ -64,40 +64,40 @@ MyApp/
 └── app.js                # Bootstrap file loaded first when app launches
 ```
 
-## Running Your App
+## Running your app
 
-### iOS Simulator
+### iOS simulator
 ```bash
 ti build -p ios -C "iPhone 15"
 ```
 
-### Android Emulator
+### Android emulator
 ```bash
 ti build -p android -C "Pixel_4_API_34"
 ```
 
-### Physical Device
+### Physical device
 ```bash
 ti build -p ios -T device
 ti build -p android -T device
 ```
 
-## Simulator vs Emulator
+## Simulator vs emulator
 
-- **iOS Simulator**: The software simulates the environment within an iOS device. It's an OS X executable that runs your cross-compiled code.
-- **Android Emulator**: Provides a virtual hardware environment that runs the actual Android OS and platform components.
+- 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.
 
-**CRITICAL**: Neither environment is a perfect representation of a physical device. Always test on real hardware before publishing.
+Neither environment is a perfect representation of a physical device. Always test on real hardware before publishing.
 
-## How Titanium Works (Under the Covers)
+## 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 necessary for compilation.
-3. **Native Build**: Titanium calls platform-specific compilers (e.g., `xcodebuild` for iOS, Gradle for Android) to build the final native application.
-4. **Encryption**: JavaScript code is encrypted when building for "production" (release) or for device. Original code is not retrievable in human-readable form.
+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
+## Best practices
 
-1. **Always test on physical devices** - Simulator/emulator isn't perfect
-2. **Use Alloy for new projects** - Better structure and maintainability
-3. **Keep App ID consistent** - Match Bundle ID (iOS) and Package ID (Android)
+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).