@maccesar/titools 2.2.11 → 2.3.0

package/skills/ti-expert/references/architecture-tiers.md

@@ -0,0 +1,248 @@
+# Titanium Architectural Maturity Tiers
+
+To ensure scalability and maintainability, Titanium projects should follow one of these three tiers based on their complexity.
+
+---
+
+# Tier 1 — Basic (Rapid Prototyping)
+
+**Best for:** Utilities, internal tools, proof of concept, learning Alloy.
+
+### Characteristics
+
+* Logic directly in `index.js`
+* Direct `$` access everywhere
+* No separation of concerns
+* No cleanup strategy
+
+### When to upgrade?
+
+* Controller > 100–150 lines
+* Logic duplicated in multiple controllers
+* UI starts feeling coupled
+
+---
+
+## Example (Tier 1)
+
+### Controller (`controllers/index.js`)
+
+```javascript
+function onButtonClick() {
+  $.label.text = "Clicked!"
+  Ti.API.info("Button was clicked")
+}
+
+$.index.open()
+```
+
+Simple. Fast. Dangerous beyond small apps.
+
+---
+
+# Tier 2 — Intermediate (Modular Alloy)
+
+**Best for:** Standard commercial applications.
+
+### Characteristics
+
+* Business logic extracted to `app/lib/`
+* Slim controllers
+* Flat organization (`lib/services`, `lib/api`)
+* Mandatory `cleanup`
+* Reusable UI components
+
+### Why this tier exists
+
+This tier separates UI from logic, but still allows services to reference global dependencies.
+
+It’s modular — but not yet decoupled.
+
+---
+
+## Example (Tier 2)
+
+### View (`views/userCard.xml`)
+
+```xml
+<Alloy>
+  <View id="cardContainer">
+    <View id="headerRow">
+      <ImageView id="userIcon" image="/images/user.png" />
+      <Label id="name" />
+    </View>
+
+    <Button id="viewProfileBtn"
+      title="View Profile"
+      onClick="onViewProfile" />
+  </View>
+</Alloy>
+```
+
+---
+
+### Controller (`controllers/userCard.js`)
+
+```javascript
+const { Navigation } = require('services/navigation')
+
+function init() {
+  const user = $.args.user
+  $.name.text = user.name
+}
+
+function onViewProfile() {
+  Navigation.open('userProfile', { userId: $.args.user.id })
+}
+
+function cleanup() {
+  $.destroy()
+}
+
+$.cleanup = cleanup
+```
+
+---
+
+### Service (`lib/services/navigation.js`)
+
+```javascript
+exports.Navigation = {
+  open(route, params = {}) {
+    const controller = Alloy.createController(route, params)
+    const view = controller.getView()
+
+    view.addEventListener('close', () => {
+      if (controller.cleanup) controller.cleanup()
+    })
+
+    view.open()
+    return controller
+  }
+}
+```
+
+---
+
+### What improves from Tier 1?
+
+* Controllers stay under control
+* Logic is reusable
+* Memory is explicitly cleaned
+* Code is easier to test
+
+But services can still depend directly on other services or globals.
+
+---
+
+# Tier 3 — Advanced / Enterprise (Service-Oriented)
+
+**Best for:** Complex applications (IDEs, platforms, multi-state apps).
+
+This is where architectural maturity changes fundamentally.
+
+---
+
+## Core Concepts
+
+### 1️⃣ Dependency Injection
+
+Services receive what they need — they don’t fetch it.
+
+### 2️⃣ Service Registry
+
+Centralized dependency wiring.
+
+### 3️⃣ ID Scoping
+
+Services receive only the UI elements they own.
+
+### 4️⃣ Encapsulation (Black Box Principle)
+
+Once a service method works, treat it as trusted.
+
+### 5️⃣ Observability
+
+All logs are structured and include service context.
+
+---
+
+## Example (Tier 3)
+
+---
+
+### Service (`lib/services/chatService.js`)
+
+```javascript
+/**
+ * @param {Object} deps
+ * @param {Object} deps.ui - Scoped UI elements
+ * @param {Object} deps.logger
+ * @param {Object} deps.designService
+ */
+module.exports = function createChatService(deps) {
+  const { ui, logger, designService } = deps
+
+  function sendMessage(text) {
+    if (!text) return
+
+    ui.sendBtn.enabled = false        // ID Scoping
+    designService.trackMessage(text)  // Inter-service communication
+
+    logger.event('message:sent', {
+      service: 'ChatService',
+      length: text.length
+    })
+  }
+
+  return {
+    sendMessage
+  }
+}
+```
+
+---
+
+### Registry (`lib/services/indexServiceRegistry.js`)
+
+```javascript
+const createChatService = require('services/chatService')
+const createDesignService = require('services/designService')
+
+module.exports = function createIndexServiceRegistry(deps) {
+  const { $, Ti, logger } = deps
+
+  // 1. Independent services
+  const designService = createDesignService({ Ti, logger })
+
+  // 2. Dependent services with scoped UI
+  const chatService = createChatService({
+    ui: {
+      sendBtn: $.sendBtn,
+      messageInput: $.messageInput
+    },
+    logger,
+    designService
+  })
+
+  return {
+    chatService,
+    designService
+  }
+}
+```
+
+---
+
+## Decision Matrix
+
+| Signal                              | Move To |
+| ----------------------------------- | ------- |
+| Controller > 100 lines              | Tier 2  |
+| Controller > 300 lines              | Tier 3  |
+| More than 50 IDs in XML             | Tier 3  |
+| Services need to talk to each other | Tier 3  |
+| Multiple application states         | Tier 3  |
+| Memory leaks appear                 | Tier 3  |
+
+---

package/skills/ti-expert/references/code-conventions.md

@@ -386,13 +386,13 @@ const Backbone = require('alloy/backbone')
 
 const EventBus = _.clone(Backbone.Events)
 
-// Named export for event constants
-exports.Events = {
+// Attach event constants directly to the bus object so they survive module.exports
+EventBus.Events = {
   USER_UPDATED: 'user:updated',
   SYNC_COMPLETE: 'sync:complete'
 }
 
-// Default export for the bus itself
+// Export the bus (EventBus.Events is accessible as a property)
 module.exports = EventBus
 
 // Usage
@@ -400,6 +400,8 @@ const EventBus = require('services/eventBus')
 const { Events } = EventBus
 ```
 
+> Note: setting `exports.Events = {...}` before `module.exports = EventBus` has no effect — the `module.exports` assignment discards the prior `exports` object. Attach constants directly to the object being exported instead.
+
 ### Re-exports (Barrel Files)
 ```javascript
 // lib/api/index.js - Barrel file

package/skills/ti-expert/references/error-handling.md

@@ -4,7 +4,10 @@
 
 ```javascript
 // lib/core/appError.js
-module.exports = class AppError extends Error {
+// IMPORTANT: Use named exports (exports.Foo), NOT module.exports = class Foo.
+// Multiple `module.exports =` assignments overwrite each other — only the last one survives.
+
+class AppError extends Error {
   constructor(message, code, statusCode = 500) {
     super(message)
     this.code = code
@@ -14,32 +17,36 @@ module.exports = class AppError extends Error {
   }
 }
 
-// Specific error types
-module.exports = class NetworkError extends AppError {
+class NetworkError extends AppError {
   constructor(message = 'Network request failed') {
     super(message, 'NETWORK_ERROR', 0)
   }
 }
 
-module.exports = class AuthError extends AppError {
+class AuthError extends AppError {
   constructor(message = 'Authentication failed') {
     super(message, 'AUTH_ERROR', 401)
   }
 }
 
-module.exports = class ValidationError extends AppError {
+class ValidationError extends AppError {
   constructor(message = 'Validation failed') {
     super(message, 'VALIDATION_ERROR', 400)
   }
 }
 
-module.exports = class NotFoundError extends AppError {
+class NotFoundError extends AppError {
   constructor(message = 'Resource not found') {
     super(message, 'NOT_FOUND', 404)
   }
 }
 
-// Error codes for reference
+exports.AppError = AppError
+exports.NetworkError = NetworkError
+exports.AuthError = AuthError
+exports.ValidationError = ValidationError
+exports.NotFoundError = NotFoundError
+
 exports.ErrorCodes = {
   NETWORK_ERROR: 'NETWORK_ERROR',
   AUTH_ERROR: 'AUTH_ERROR',

package/skills/ti-expert/references/examples.md

@@ -736,9 +736,11 @@ function init() {
 }
 
 function onTabFocus(e) {
-  // Analytics tracking
+  // Track tab changes via your analytics service
+  // Note: Ti.Analytics was removed from the Titanium SDK.
+  // Use a third-party analytics service (e.g., Firebase, Segment) instead.
   const tabNames = ['home', 'search', 'cart', 'profile']
-  Ti.Analytics.featureEvent(`tab:${tabNames[e.index]}`)
+  Analytics.track(`tab:${tabNames[e.index]}`)
 }
 
 function onCartUpdated({ itemCount }) {

package/skills/ti-expert/references/performance-optimization.md

@@ -212,12 +212,14 @@ $.cleanup = cleanup
 ```javascript
 // lib/services/database.js
 exports.DB = {
-  // Use transactions for multiple writes
+  // Use transactions to speed batch inserts
+  // Per official docs: use db.execute('BEGIN') / db.execute('COMMIT') — there are no
+  // dedicated begin_transaction() / commit() / rollback() methods on Ti.Database.DB.
   batchInsert(items) {
     const db = Ti.Database.open('mydb')
 
     try {
-      db.begin_transaction()
+      db.execute('BEGIN')
 
       items.forEach(item => {
         db.execute(
@@ -228,12 +230,12 @@ exports.DB = {
         )
       })
 
-      db.commit()
+      db.execute('COMMIT')
 
       console.log(`Inserted ${items.length} items`)
 
     } catch (e) {
-      db.rollback()
+      db.execute('ROLLBACK')
       console.error('Batch insert failed', e)
       throw e
 
@@ -574,14 +576,14 @@ function cleanup() {
 
 ### Common use cases
 
-| Pattern | Use Case | Delay |
+| Pattern  | Use Case         | Delay        |
 | -------- | ---------------- | ------------ |
-| Debounce | Search input | 300ms |
-| Debounce | Auto-save | 1000ms |
-| Debounce | Window resize | 150ms |
-| Throttle | Scroll events | 50-100ms |
+| Debounce | Search input     | 300ms        |
+| Debounce | Auto-save        | 1000ms       |
+| Debounce | Window resize    | 150ms        |
+| Throttle | Scroll events    | 50-100ms     |
 | Throttle | Mouse/touch move | 16ms (60fps) |
-| Throttle | API polling | 5000ms+ |
+| Throttle | API polling      | 5000ms+      |
 
 ### Combined pattern for real-time + final
 
@@ -622,18 +624,18 @@ function cleanup() {
 
 ## Performance checklist
 
-| Area | Check |
+| Area          | Check                                   |
 | ------------- | --------------------------------------- |
-| **Bridge** | Cached Ti.Platform properties |
-| **Bridge** | Using applyProperties for updates |
-| **Bridge** | TSS styles instead of inline attributes |
-| **Memory** | All global listeners cleaned up |
-| **Memory** | Heavy objects nulled in cleanup |
-| **Memory** | Images resized appropriately |
-| **Database** | Using transactions for batch ops |
-| **Database** | Indexes on frequently queried columns |
-| **Database** | ResultSets and DB handles closed |
-| **Animation** | Using native animations, not intervals |
-| **Animation** | GPU-accelerated properties preferred |
-| **Timing** | Debounce on search/input |
-| **Timing** | Throttle on scroll/touch events |
+| **Bridge**    | Cached Ti.Platform properties           |
+| **Bridge**    | Using applyProperties for updates       |
+| **Bridge**    | TSS styles instead of inline attributes |
+| **Memory**    | All global listeners cleaned up         |
+| **Memory**    | Heavy objects nulled in cleanup         |
+| **Memory**    | Images resized appropriately            |
+| **Database**  | Using transactions for batch ops        |
+| **Database**  | Indexes on frequently queried columns   |
+| **Database**  | ResultSets and DB handles closed        |
+| **Animation** | Using native animations, not intervals  |
+| **Animation** | GPU-accelerated properties preferred    |
+| **Timing**    | Debounce on search/input                |
+| **Timing**    | Throttle on scroll/touch events         |

package/skills/ti-expert/references/security-device.md

@@ -502,6 +502,9 @@ exports.SecurityService = {
   },
 
   _showBlockedScreen() {
+    // Note: iOS guidelines prohibit programmatically terminating an app.
+    // The best practice is to show a blocking dialog and prevent further interaction.
+    // On Android you can call Ti.Android.currentActivity.finish() to close the activity.
     const dialog = Ti.UI.createAlertDialog({
       title: L('security_blocked_title'),
       message: L('security_blocked_msg'),
@@ -509,10 +512,10 @@ exports.SecurityService = {
     })
 
     dialog.addEventListener('click', () => {
-      // Close the app (iOS) or minimize (Android)
-      if (OS_IOS) {
-        Ti.Platform.openURL('prefs:root=General')
+      if (OS_ANDROID) {
+        Ti.Android.currentActivity.finish()
       }
+      // On iOS: leave the dialog visible — Apple guidelines prohibit force-quitting apps.
     })
 
     dialog.show()
@@ -550,15 +553,15 @@ setInterval(() => {
 
 ## Security checklist
 
-| Category | Check | Implementation |
+| Category       | Check                      | Implementation           |
 | -------------- | -------------------------- | ------------------------ |
-| **Biometrics** | Use ti.identity for auth | BiometricService wrapper |
-| **Biometrics** | Never store biometric data | System handles storage |
-| **Biometrics** | Fallback to password | Always offer alternative |
-| **Deep Links** | Whitelist allowed schemes | ALLOWED_SCHEMES constant |
-| **Deep Links** | Whitelist allowed hosts | ALLOWED_HOSTS constant |
-| **Deep Links** | Sanitize all parameters | _sanitizeParams() |
-| **Deep Links** | Check auth requirements | requiresAuth per route |
-| **Integrity** | Check for jailbreak/root | checkDeviceIntegrity() |
-| **Integrity** | Define security policy | block/restrict/warn |
-| **Integrity** | Log security events | Always log compromises |
+| **Biometrics** | Use ti.identity for auth   | BiometricService wrapper |
+| **Biometrics** | Never store biometric data | System handles storage   |
+| **Biometrics** | Fallback to password       | Always offer alternative |
+| **Deep Links** | Whitelist allowed schemes  | ALLOWED_SCHEMES constant |
+| **Deep Links** | Whitelist allowed hosts    | ALLOWED_HOSTS constant   |
+| **Deep Links** | Sanitize all parameters    | _sanitizeParams()        |
+| **Deep Links** | Check auth requirements    | requiresAuth per route   |
+| **Integrity**  | Check for jailbreak/root   | checkDeviceIntegrity()   |
+| **Integrity**  | Define security policy     | block/restrict/warn      |
+| **Integrity**  | Log security events        | Always log compromises   |