@maccesar/titools 5.2.5 → 5.4.0

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

@@ -1,279 +1,129 @@
-# CommonJS advanced patterns
+# Using modules
 
-For more on CommonJS in Titanium, see the official CommonJS Modules guide in the Titanium SDK documentation.
 
-## Definitions
+Two different things get added to a Titanium project and both are called
+dependencies.
 
-- 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.
+A **native module** wraps platform code the core SDK does not expose: Bluetooth,
+maps, barcodes. It ships as a built binary per platform.
 
-## 1. Stateful modules (singleton pattern)
+An **npm package** is JavaScript. If it runs without Node's built-ins and
+without a browser, it will probably run here.
 
-Modules in Titanium are created once per JavaScript context and reused on subsequent `require()` calls. This makes them useful for shared state.
+## Native modules
 
-### Example: stateful counter module
+The [modules directory](https://titaniumsdk.com/modules) lists what TiDev maintains. Installing one is
+three steps: unpack it, declare it, require it.
 
-```javascript
-// app/lib/counter.js
-let _count = 0
+> [!NOTE]
+> There is no install command yet. `ti module` has one subcommand, `list`, so
+> unpacking is done by hand. `ti module install` and `ti module search` are
+> planned; until they ship, this is the path.
 
-exports.increment = () => {
-  _count++
-}
+Download the release archive for the module and unzip it into a `modules`
+directory beside `tiapp.xml`. The archive already carries the right shape, so
+unzipping it in place gives you:
 
-exports.getCount = () => {
-  return _count
-}
-
-exports.reset = () => {
-  _count = 0
-}
+```
+modules/
+  android/ti.map/5.7.0/
+  iphone/ti.map/7.3.1/
 ```
 
-Usage: multiple controllers that require this module share the same `_count` state.
+That is `modules/<platform>/<id>/<version>/`, and the platform directory is
+`android`, `iphone` or `commonjs` - `iphone` covers iPad and macOS too.
 
-A module is created once per Titanium JavaScript context. Additional contexts create new module instances.
+Check the CLI can see it:
 
-## 2. Native/compiled modules
+```sh
+ti module list
+```
 
-When `require()` is called, Titanium checks for a native/compiled module before it looks for a JavaScript module. Native modules take priority.
+It reports three scopes - project, configured paths, and global - so the output
+also tells you which copy a build will pick up.
 
-Native modules are identified by a single string and configured in `tiapp.xml`:
+Then declare it in `tiapp.xml`, per platform:
 
 ```xml
 <modules>
-  <module version="1.0">ti.paypal</module>
+  <module platform="android">ti.map</module>
+  <module platform="iphone">ti.map</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
+Both steps are needed. A module on disk that `tiapp.xml` does not name is not
+built in, and the failure is a `require` that returns nothing rather than an
+error at build time.
 
-```javascript
-exports.sayHello = (name) => {
-  Ti.API.info(`Hello ${name}`)
-}
+Then require it by id:
 
-exports.version = 1.4
+```js
+const Map = require('ti.map');
 ```
 
-### Constructor pattern (`module.exports`)
-
-```javascript
-class Person {
-  constructor(firstName, lastName) {
-    this.firstName = firstName
-    this.lastName = lastName
-  }
+Pin a version when more than one is unpacked and you care which one you get:
 
-  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
+```xml
+<module platform="android" version="5.7.0">ti.map</module>
 ```
 
-Usage:
-```javascript
-const Geo = require('lib/geo')
+Without a version the newest installed copy wins, which means a machine with
+two versions in `modules/` and a colleague's machine with one can produce
+different builds from the same commit.
 
-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())
-```
+> [!IMPORTANT]
+> A module is native code, so it is built for specific platforms and against a
+> range of SDK versions. A module that has not been rebuilt for a newer Titanium
+> SDK may fail at build time with a linker error rather than anything that names
+> the module. Check the module's own page for the versions it supports.
 
-## 8. Inter-module state sharing
+### Where modules live
 
-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.
+`modules/<platform>/<moduleid>/<version>/` in the project, which is committed
+like any other source. Some teams keep them out of version control and install
+in CI instead; either works, as long as the whole team does the same thing.
 
-```javascript
-// app/lib/statefulModule.js
-let _stepVal = 5
+Unpacking into the global directory instead makes the module available to every
+project on that machine and to nobody else's, which makes a build depend on the
+machine it runs on. Prefer the project-local copy. On macOS the global one is
+`~/Library/Application Support/Titanium/modules`, and `ti module list` prints
+the full path of everything it finds.
 
-exports.setPointStep = (value) => {
-  _stepVal = value
-}
+## npm packages
 
-exports.getPointStep = () => {
-  return _stepVal
-}
+`package.json` in the project root, and `npm install` as normal:
 
-exports.stepVal = _stepVal // This is a copy of _stepVal (value: 5)
+```sh
+npm install lodash
 ```
 
-```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
+```js
+const _ = require('lodash');
 ```
 
-Rule: use getter/setter functions for stateful values. Direct property exports of primitives are snapshots at module load time.
+Titanium bundles what is in `node_modules` at build time. There is no
+resolution at runtime, so a package pulled in dynamically by name computed at
+runtime will not be there.
 
-## 9. Antipatterns to avoid
+**Check runtime dependencies:** Titanium is not a full Node.js or browser runtime. Some Node-compatible shims (`fs`, `path`, `os`, `buffer`, `events`, `process`) exist in the released API; verify the exact supported subset. Packages requiring unavailable Node APIs such as `child_process`, a DOM or Node native bindings do not work unchanged. A package that only touches `Ti.*` and plain JavaScript is fine.
+Check before adopting a large dependency; the failure arrives at runtime as an
+undefined require.
 
-### Do not assign directly to `exports`
+Keep `node_modules` out of version control as you would anywhere else.
 
-```javascript
-// Wrong
-function Person() {}
-exports = Person
+## Which one do I need
 
-// Correct
-module.exports = Person
-```
+If it talks to hardware, the operating system, or a platform SDK, it is a
+native module and somebody has to have written it. If it is an algorithm, a
+parser, or a client for an HTTP API, it is probably an npm package.
 
-### Do not mix `module.exports` and `exports.*`
-
-```javascript
-// Discouraged
-module.exports = Person
-exports.foo = 'bar'
-
-// Use one consistently
-```
+If neither exists, writing a native module is covered under Extending Titanium.
 
-### 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
-}
-```
+## Next
 
-## 11. Node.js compatibility
+[Debugging and profiling](https://titaniumsdk.com/docs/build/debugging) covers finding out why the
+thing you just added is not working.
 
-Titanium supports Node.js module patterns and `require()` resolution. Node.js modules can often be used directly.
+## Application CommonJS paths
 
-For details, refer to the official Titanium Node.js guide.
+Classic `Resources/myModule.js` and Alloy `app/lib/myModule.js` are required as `require('myModule')`; the Alloy source prefix `app/lib/` is not a runtime module prefix. Use literal native requires by ID and declare the module first. Check the selected SDK's versioned API for Node-compatible shims rather than assuming full Node behavior.

package/skills/ti-guides/references/compatibility-matrix.md

@@ -1,89 +1,50 @@
-# Compatibility matrix
+# Titanium compatibility matrix
 
-Which JDK, Node.js, Xcode and Android SDK versions a given Titanium SDK release can build with. Components outside the min/max ranges below are not compatible.
+## Released baseline: SDK 13.4.1.GA
 
-Only the currently supported ranges are reproduced here. Upstream also keeps collapsed tables of long-unsupported ranges (back to Titanium 1.7); if a project is pinned to something older than the rows below, consult the upstream matrix directly.
+These are the declared ranges for **13.4.1.GA**, not promises about every future release. Check the [rendered compatibility tables](https://titaniumsdk.com/docs/reference/compatibility.md) and the [versioned API](https://titaniumsdk.com/docs/sdk/13.4.1) for another SDK. Raw website Markdown contains generated-table directives; read the rendered page to obtain the actual rows. Unreleased SDK 14 requirements are outside this baseline.
 
-<!-- TOC-START -->
-## Contents
+| Component | SDK 13.4.1 declaration |
+| --- | --- |
+| Node.js used by SDK | >=20.18.1 |
+| Titanium CLI | >=8.0.0 |
+| JDK | >=17.x |
+| Android SDK platforms | 23.x through 36.x |
+| Android Build Tools | 30.0.2 through 35.x |
+| Android Platform Tools | 33.x |
+| Android SDK Tools | <=35.x |
+| Android NDK, for native compilation | r21 through r22b |
+| Xcode | 15.0 through 26.x |
+| iOS SDK | 17.0 through 26.x |
 
-- [1. Operating system](#1-operating-system)
-- [2. Java Development Kit](#2-java-development-kit)
-- [3. Node.js](#3-nodejs)
-- [4. Android](#4-android)
-- [5. iOS and Xcode](#5-ios-and-xcode)
-- [6. Which platform can build what](#6-which-platform-can-build-what)
+A platform that can be detected is not necessarily the runtime floor or the default compile target. For 13.4.1 the Android minimum runtime is API 24, default compile/target is API 36, iOS minimum runtime is 15.0, and watchOS minimum is 8.0. Setting a lower `min-ios-ver` does not lower the SDK floor. Module compatibility is separate: check each native module's supported SDK, architecture and platform versions.
 
-<!-- TOC-END -->
+## SDK and CLI requirements differ
 
-## 1. Operating system
+The current CLI 9.1.0 requires Node >=22.19.0 even though SDK 13.4.1 declares >=20.18.1. Use Node 22.19+ in the 22 line or Node 24 with that pairing. SDK 13.4.1's `ioslib`/`node-ios-device` dependencies provide prebuilt bindings through Node 24; Node 26 can fail while rebuilding/loading them. Do not infer unrestricted practical compatibility from a lower-bound-only SDK declaration. Use Node 24 for this released baseline rather than adopting SDK 14 instructions before GA.
 
-| Operating system | Version |
-|---|---|
-| macOS | 10.11.5 and later |
-| Windows | Windows 7 and later (Android) |
-| Linux | Tested on Fedora and (K)Ubuntu; others should work |
+JDK source/target bytecode settings such as `android.javac.source` do not identify the JDK that runs Gradle. Check `javac -version`, `JAVA_HOME` and `ti info` independently.
 
-## 2. Java Development Kit
+## Host platforms and native tooling
 
-The JDK is required to build Titanium apps and modules for Android. OpenJDK or Oracle both work.
+| Host | Android | iOS and Mac Catalyst |
+| --- | --- | --- |
+| macOS | Yes | Yes, through Xcode |
+| Windows | Yes | No |
+| Linux | Yes | No |
 
-| Titanium SDK version | Min JDK | Max JDK |
-|---|---|---|
-| 13.3.0 - latest | 18 | 25 |
-| 12.8.0 - 13.2.0 | 18 | 21 |
+The host OS must also support the installed Node, JDK, Android tools and Xcode; old archive claims such as Windows 7 or macOS 10.11 are not current installation advice. On macOS open Xcode once, finish its installation, and select the intended copy with `sudo xcode-select -s /Applications/Xcode.app`.
 
-`12.0.0 - 12.7.0` (JDK 11-17) moved to the unsupported table when 13.3.0 shipped.
+Components newer than the SDK's tested range can produce warnings while builds continue; a warning alone does not establish either failure or support. Diagnose a failing build with the tested version first. Pin Android Build Tools with `ti config android.buildTools.selectedVersion 35.0.0` when needed. NDK warnings are irrelevant to ordinary app builds that do not compile native code.
 
-## 3. Node.js
+## Verify the selected environment
 
-Node.js is required to install and run the Titanium SDK. On Windows, enable `dev mode` in Windows settings for Node to work correctly.
+```sh
+node -v
+javac -version
+ti -v
+ti sdk list
+ti info
+```
 
-| Titanium SDK version | Min Node | Max Node |
-|---|---|---|
-| 13.1.1 - latest | 20.x | 24.x |
-| 13.0.0 - 13.1.0 | 20.x | 22.x |
-| 12.6.0 - 12.8.0 | 18.x | 22.x |
-
-## 4. Android
-
-As of Titanium 9.0.0 the build system downloads the needed Android SDK platforms and tools automatically. Upgrade those packages only between major projects — changes there have broken the Titanium toolchain several times.
-
-| Titanium SDK version | Min target (`android:targetSdkVersion`) | Max target | Min supported (`android:minSdkVersion`) |
-|---|---|---|---|
-| 13.1.0+ | 15.x (API 35) | 15.x (API 35) | 7.x (API 24) |
-| 12.8.0 - 13.0.1 | 15.x (API 35) | 15.x (API 35) | 5.x (API 21) |
-| 12.5.0 - 12.8.0 | 14.x (API 34) | 14.x (API 34) | 5.x (API 21) |
-| 12.0.0 - 12.5.0 | 13.x (API 33) | 13.x (API 33) | 5.x (API 21) |
-
-A `android:targetSDKVersion` set in `tiapp.xml` must fall inside the min/max target range of the SDK in use.
-
-> **Note:** Titanium SDK 13.4.0 is described in its release note as *preparing the SDK for Android target SDK 36*. The matrix above still lists API 35 as the maximum; treat API 36 as in-progress rather than as a supported target until the matrix says otherwise.
-
-Developing native Android add-on modules on macOS also requires the Xcode command line tools.
-
-## 5. iOS and Xcode
-
-Building for iOS requires macOS — Apple's license agreement allows iOS development only on Apple hardware.
-
-| Titanium SDK version | Min Xcode | Max Xcode | Notes |
-|---|---|---|---|
-| 12.6.3 - latest | 12.0.0 | 16.x | Full support for iOS 18.4 |
-| 12.2.0 - 12.6.2 | 12.0.0 | 16.2 | Full support for iOS 17 |
-| 10.1.0 - 12.1.2 | 11.0.0 | 13.x | Full support for iOS 15 |
-
-| Titanium SDK version | Min iOS SDK | Max iOS SDK | Min target iOS | Max target iOS |
-|---|---|---|---|---|
-| 12.2.0 - latest | 13.0.0 | 17.x | 12.0 | 17.x |
-| 10.1.0 - 12.1.2 | 13.0.0 | 15.x | 12.0 | 15.x |
-
-> **Note:** these two tables lag behind the release notes. Titanium SDK 13.3.0 shipped *support for Xcode 27 and iOS 27*, which no row above reflects. Where they disagree, the release note is the newer statement — see [sdk-release-notes.md](sdk-release-notes.md).
-
-## 6. Which platform can build what
-
-| Target | macOS | Windows | Linux |
-|---|---|---|---|
-| Android | Yes | Yes | Yes |
-| iOS | Yes | No | No |
-
-Anything marked *pre-release* upstream — Beta, Developer Preview, Release Candidate, and continuous builds — is not officially supported.
+Use `ti info -t ios` or `ti info -t android` to narrow detection. Pin `<sdk-version>13.4.1.GA</sdk-version>` in `tiapp.xml` for reproducible builds; an explicit `--sdk` overrides it for one invocation. Development snapshots and release candidates are for testing, not a replacement for a supported GA production baseline.