@axintai/compiler 0.2.1 → 0.3.0

package/dist/sdk/index.js

@@ -29,12 +29,41 @@ var param = {
    * for `param.int` to preserve v0.1.x compatibility and will be removed
    * in v1.0.0.
    */
-  number: make("number")
+  number: make("number"),
+  /**
+   * Entity reference parameter. The entity name must match a
+   * `defineEntity()` call in the same file or project.
+   */
+  entity: (entityName, description, config) => ({
+    type: "entity",
+    entityName,
+    description,
+    ...config
+  }),
+  /**
+   * Parameter with dynamic option suggestions provided at runtime
+   * by a DynamicOptionsProvider. The `providerName` maps to a
+   * generated Swift `DynamicOptionsProvider` struct.
+   */
+  dynamicOptions: (providerName, innerParam) => {
+    const { type: innerType, description, ...rest } = innerParam;
+    return {
+      type: "dynamicOptions",
+      providerName,
+      innerType,
+      description,
+      ...rest
+    };
+  }
 };
 function defineIntent(config) {
   return config;
 }
+function defineEntity(config) {
+  return config;
+}
 export {
+  defineEntity,
   defineIntent,
   param
 };

package/dist/sdk/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/sdk/index.ts"],"sourcesContent":["/**\n * axint — Decorators and types for defining Apple App Intents\n *\n * The canonical way to define an App Intent in TypeScript. The axint\n * compiler parses files written against this SDK and emits a native\n * Swift `AppIntent` struct (plus optional Info.plist and entitlements\n * fragments) suitable for dropping into an Xcode project.\n *\n * @example\n * ```typescript\n * import { defineIntent, param } from \"axint\";\n *\n * export default defineIntent({\n *   name: \"CreateEvent\",\n *   title: \"Create Calendar Event\",\n *   description: \"Creates a new event in the user's calendar\",\n *   domain: \"productivity\",\n *   entitlements: [\"com.apple.developer.siri\"],\n *   infoPlistKeys: {\n *     NSCalendarsUsageDescription: \"Axint needs calendar access to create events.\",\n *   },\n *   params: {\n *     title: param.string(\"Event title\"),\n *     date: param.date(\"Event date\"),\n *     durationMinutes: param.int(\"Duration in minutes\", { default: 30 }),\n *     allDay: param.boolean(\"Is all-day event\", { required: false }),\n *   },\n *   perform: async ({ title, date }) => {\n *     return { success: true, id: \"evt_123\" };\n *   },\n * });\n * ```\n *\n * @packageDocumentation\n */\n\n// ─── Shared Config ───────────────────────────────────────────────────\n\n/** Configuration for a single parameter. */\nexport interface ParamConfig {\n  /** Display name for this parameter (auto-generated from field name if omitted). */\n  title?: string;\n  /** Human-readable description shown in Siri/Shortcuts. */\n  description: string;\n  /** Default value if the user doesn't provide one. */\n  default?: unknown;\n  /**\n   * Whether this parameter is required. Defaults to `true`.\n   * Set to `false` to make the Swift property optional (`Type?`).\n   */\n  required?: boolean;\n}\n\ntype ParamFactory<T extends string> = (\n  description: string,\n  config?: Partial<ParamConfig>\n) => { type: T; description: string } & Partial<ParamConfig>;\n\nfunction make<T extends string>(type: T): ParamFactory<T> {\n  return (description, config) => ({\n    type,\n    description,\n    ...config,\n  });\n}\n\n// ─── Parameter Type Helpers ──────────────────────────────────────────\n\n/**\n * Parameter type helpers for defining intent parameters.\n *\n * Each helper maps directly to a Swift App Intents type:\n *\n * | Helper            | Swift type                    |\n * |-------------------|-------------------------------|\n * | `param.string`    | `String`                      |\n * | `param.int`       | `Int`                         |\n * | `param.double`    | `Double`                      |\n * | `param.float`     | `Float`                       |\n * | `param.boolean`   | `Bool`                        |\n * | `param.date`      | `Date`                        |\n * | `param.duration`  | `Measurement<UnitDuration>`   |\n * | `param.url`       | `URL`                         |\n * | `param.number` *  | `Int` *(deprecated alias)*    |\n *\n * @example\n * ```typescript\n * params: {\n *   name: param.string(\"User's name\"),\n *   age: param.int(\"Age in years\"),\n *   height: param.double(\"Height in meters\"),\n *   notify: param.boolean(\"Send notification\", { required: false }),\n *   when: param.date(\"Scheduled date\"),\n *   length: param.duration(\"How long\"),\n *   link: param.url(\"Resource URL\"),\n * }\n * ```\n */\nexport const param = {\n  /** String parameter → Swift `String` */\n  string: make(\"string\"),\n  /** 64-bit signed integer → Swift `Int` */\n  int: make(\"int\"),\n  /** Double-precision float → Swift `Double` */\n  double: make(\"double\"),\n  /** Single-precision float → Swift `Float` */\n  float: make(\"float\"),\n  /** Boolean parameter → Swift `Bool` */\n  boolean: make(\"boolean\"),\n  /** Date parameter → Swift `Date` */\n  date: make(\"date\"),\n  /** Duration parameter → Swift `Measurement<UnitDuration>` */\n  duration: make(\"duration\"),\n  /** URL parameter → Swift `URL` */\n  url: make(\"url\"),\n  /**\n   * @deprecated Use `param.int` (or `param.double` / `param.float`) for\n   * explicit Swift numeric fidelity. `param.number` is kept as an alias\n   * for `param.int` to preserve v0.1.x compatibility and will be removed\n   * in v1.0.0.\n   */\n  number: make(\"number\"),\n};\n\n// ─── Intent Definition ───────────────────────────────────────────────\n\n/** The full intent definition including name, metadata, params, and perform function. */\nexport interface IntentDefinition<\n  TParams extends Record<string, ReturnType<(typeof param)[keyof typeof param]>>,\n> {\n  /** PascalCase name for the generated Swift struct (e.g., \"CreateEvent\"). */\n  name: string;\n  /** Display name shown in Siri and Shortcuts. */\n  title: string;\n  /** Human-readable description of what this intent does. */\n  description: string;\n  /**\n   * Apple App Intent Domain for categorization.\n   * Common values: \"messaging\", \"productivity\", \"finance\", \"health\",\n   * \"commerce\", \"media\", \"navigation\", \"smart-home\"\n   */\n  domain?: string;\n  /** Siri/Shortcuts category for discoverability. */\n  category?: string;\n  /**\n   * Entitlements required by this intent.\n   * Example: `[\"com.apple.developer.siri\", \"com.apple.developer.healthkit\"]`\n   * The compiler can emit a matching `.entitlements` fragment.\n   */\n  entitlements?: string[];\n  /**\n   * Info.plist keys required by this intent, mapped to their usage\n   * description strings.\n   * Example: `{ NSCalendarsUsageDescription: \"We need calendar access\" }`\n   */\n  infoPlistKeys?: Record<string, string>;\n  /** Whether the intent should be exposed to Spotlight indexing. */\n  isDiscoverable?: boolean;\n  /** Parameter definitions using `param.*` helpers. */\n  params: TParams;\n  /**\n   * The perform function (used for local testing/type-checking).\n   * Note: The compiler generates a placeholder `perform()` in Swift —\n   * you'll implement the actual logic in your Xcode project.\n   */\n  perform: (params: {\n    [K in keyof TParams]: unknown;\n  }) => Promise<unknown>;\n}\n\n/**\n * Define an Apple App Intent for compilation to Swift.\n *\n * This is the main entry point for the Axint SDK. The returned definition\n * is parsed by the Axint compiler and transformed into a native Swift\n * `AppIntent` struct.\n *\n * @param config - The intent definition\n * @returns The same config (identity function for type inference)\n *\n * @example\n * ```typescript\n * export default defineIntent({\n *   name: \"SendMessage\",\n *   title: \"Send Message\",\n *   description: \"Sends a message to a contact\",\n *   domain: \"messaging\",\n *   params: {\n *     recipient: param.string(\"Who to send the message to\"),\n *     body: param.string(\"The message content\"),\n *   },\n *   perform: async ({ recipient, body }) => {\n *     return { sent: true };\n *   },\n * });\n * ```\n */\nexport function defineIntent<\n  TParams extends Record<string, ReturnType<(typeof param)[keyof typeof param]>>,\n>(config: IntentDefinition<TParams>): IntentDefinition<TParams> {\n  return config;\n}\n"],"mappings":";AA0DA,SAAS,KAAuB,MAA0B;AACxD,SAAO,CAAC,aAAa,YAAY;AAAA,IAC/B;AAAA,IACA;AAAA,IACA,GAAG;AAAA,EACL;AACF;AAkCO,IAAM,QAAQ;AAAA;AAAA,EAEnB,QAAQ,KAAK,QAAQ;AAAA;AAAA,EAErB,KAAK,KAAK,KAAK;AAAA;AAAA,EAEf,QAAQ,KAAK,QAAQ;AAAA;AAAA,EAErB,OAAO,KAAK,OAAO;AAAA;AAAA,EAEnB,SAAS,KAAK,SAAS;AAAA;AAAA,EAEvB,MAAM,KAAK,MAAM;AAAA;AAAA,EAEjB,UAAU,KAAK,UAAU;AAAA;AAAA,EAEzB,KAAK,KAAK,KAAK;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOf,QAAQ,KAAK,QAAQ;AACvB;AA2EO,SAAS,aAEd,QAA8D;AAC9D,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../../src/sdk/index.ts"],"sourcesContent":["/**\n * axint — Decorators and types for defining Apple App Intents\n *\n * The canonical way to define an App Intent in TypeScript. The axint\n * compiler parses files written against this SDK and emits a native\n * Swift `AppIntent` struct (plus optional Info.plist and entitlements\n * fragments) suitable for dropping into an Xcode project.\n *\n * @example\n * ```typescript\n * import { defineIntent, param } from \"@axintai/compiler\";\n *\n * export default defineIntent({\n *   name: \"CreateEvent\",\n *   title: \"Create Calendar Event\",\n *   description: \"Creates a new event in the user's calendar\",\n *   domain: \"productivity\",\n *   entitlements: [\"com.apple.developer.siri\"],\n *   infoPlistKeys: {\n *     NSCalendarsUsageDescription: \"Axint needs calendar access to create events.\",\n *   },\n *   params: {\n *     title: param.string(\"Event title\"),\n *     date: param.date(\"Event date\"),\n *     durationMinutes: param.int(\"Duration in minutes\", { default: 30 }),\n *     allDay: param.boolean(\"Is all-day event\", { required: false }),\n *   },\n *   perform: async ({ title, date }) => {\n *     return { success: true, id: \"evt_123\" };\n *   },\n * });\n * ```\n *\n * @packageDocumentation\n */\n\n// ─── Shared Config ───────────────────────────────────────────────────\n\n/** Configuration for a single parameter. */\nexport interface ParamConfig {\n  /** Display name for this parameter (auto-generated from field name if omitted). */\n  title?: string;\n  /** Human-readable description shown in Siri/Shortcuts. */\n  description: string;\n  /** Default value if the user doesn't provide one. */\n  default?: unknown;\n  /**\n   * Whether this parameter is required. Defaults to `true`.\n   * Set to `false` to make the Swift property optional (`Type?`).\n   */\n  required?: boolean;\n}\n\ntype ParamFactory<T extends string> = (\n  description: string,\n  config?: Partial<ParamConfig>\n) => { type: T; description: string } & Partial<ParamConfig>;\n\nfunction make<T extends string>(type: T): ParamFactory<T> {\n  return (description, config) => ({\n    type,\n    description,\n    ...config,\n  });\n}\n\n// ─── Parameter Type Helpers ──────────────────────────────────────────\n\n/**\n * Parameter type helpers for defining intent parameters.\n *\n * Each helper maps directly to a Swift App Intents type:\n *\n * | Helper            | Swift type                    |\n * |-------------------|-------------------------------|\n * | `param.string`    | `String`                      |\n * | `param.int`       | `Int`                         |\n * | `param.double`    | `Double`                      |\n * | `param.float`     | `Float`                       |\n * | `param.boolean`   | `Bool`                        |\n * | `param.date`      | `Date`                        |\n * | `param.duration`  | `Measurement<UnitDuration>`   |\n * | `param.url`       | `URL`                         |\n * | `param.number` *  | `Int` *(deprecated alias)*    |\n *\n * @example\n * ```typescript\n * params: {\n *   name: param.string(\"User's name\"),\n *   age: param.int(\"Age in years\"),\n *   height: param.double(\"Height in meters\"),\n *   notify: param.boolean(\"Send notification\", { required: false }),\n *   when: param.date(\"Scheduled date\"),\n *   length: param.duration(\"How long\"),\n *   link: param.url(\"Resource URL\"),\n * }\n * ```\n */\nexport const param = {\n  /** String parameter → Swift `String` */\n  string: make(\"string\"),\n  /** 64-bit signed integer → Swift `Int` */\n  int: make(\"int\"),\n  /** Double-precision float → Swift `Double` */\n  double: make(\"double\"),\n  /** Single-precision float → Swift `Float` */\n  float: make(\"float\"),\n  /** Boolean parameter → Swift `Bool` */\n  boolean: make(\"boolean\"),\n  /** Date parameter → Swift `Date` */\n  date: make(\"date\"),\n  /** Duration parameter → Swift `Measurement<UnitDuration>` */\n  duration: make(\"duration\"),\n  /** URL parameter → Swift `URL` */\n  url: make(\"url\"),\n  /**\n   * @deprecated Use `param.int` (or `param.double` / `param.float`) for\n   * explicit Swift numeric fidelity. `param.number` is kept as an alias\n   * for `param.int` to preserve v0.1.x compatibility and will be removed\n   * in v1.0.0.\n   */\n  number: make(\"number\"),\n\n  /**\n   * Entity reference parameter. The entity name must match a\n   * `defineEntity()` call in the same file or project.\n   */\n  entity: (entityName: string, description: string, config?: Partial<ParamConfig>) => ({\n    type: \"entity\" as const,\n    entityName,\n    description,\n    ...config,\n  }),\n\n  /**\n   * Parameter with dynamic option suggestions provided at runtime\n   * by a DynamicOptionsProvider. The `providerName` maps to a\n   * generated Swift `DynamicOptionsProvider` struct.\n   */\n  dynamicOptions: (\n    providerName: string,\n    innerParam: ReturnType<ParamFactory<string>>\n  ) => {\n    const { type: innerType, description, ...rest } = innerParam;\n    return {\n      type: \"dynamicOptions\" as const,\n      providerName,\n      innerType,\n      description,\n      ...rest,\n    };\n  },\n};\n\n// ─── Intent Definition ───────────────────────────────────────────────\n\n/** The full intent definition including name, metadata, params, and perform function. */\nexport interface IntentDefinition<\n  TParams extends Record<string, ReturnType<(typeof param)[keyof typeof param]>>,\n> {\n  /** PascalCase name for the generated Swift struct (e.g., \"CreateEvent\"). */\n  name: string;\n  /** Display name shown in Siri and Shortcuts. */\n  title: string;\n  /** Human-readable description of what this intent does. */\n  description: string;\n  /**\n   * Apple App Intent Domain for categorization.\n   * Common values: \"messaging\", \"productivity\", \"finance\", \"health\",\n   * \"commerce\", \"media\", \"navigation\", \"smart-home\"\n   */\n  domain?: string;\n  /** Siri/Shortcuts category for discoverability. */\n  category?: string;\n  /**\n   * Entitlements required by this intent.\n   * Example: `[\"com.apple.developer.siri\", \"com.apple.developer.healthkit\"]`\n   * The compiler can emit a matching `.entitlements` fragment.\n   */\n  entitlements?: string[];\n  /**\n   * Info.plist keys required by this intent, mapped to their usage\n   * description strings.\n   * Example: `{ NSCalendarsUsageDescription: \"We need calendar access\" }`\n   */\n  infoPlistKeys?: Record<string, string>;\n  /** Whether the intent should be exposed to Spotlight indexing. */\n  isDiscoverable?: boolean;\n  /** Parameter definitions using `param.*` helpers. */\n  params: TParams;\n  /**\n   * The perform function (used for local testing/type-checking).\n   * Note: The compiler generates a placeholder `perform()` in Swift —\n   * you'll implement the actual logic in your Xcode project.\n   */\n  perform: (params: {\n    [K in keyof TParams]: unknown;\n  }) => Promise<unknown>;\n}\n\n/**\n * Define an Apple App Intent for compilation to Swift.\n *\n * This is the main entry point for the Axint SDK. The returned definition\n * is parsed by the Axint compiler and transformed into a native Swift\n * `AppIntent` struct.\n *\n * @param config - The intent definition\n * @returns The same config (identity function for type inference)\n *\n * @example\n * ```typescript\n * export default defineIntent({\n *   name: \"SendMessage\",\n *   title: \"Send Message\",\n *   description: \"Sends a message to a contact\",\n *   domain: \"messaging\",\n *   params: {\n *     recipient: param.string(\"Who to send the message to\"),\n *     body: param.string(\"The message content\"),\n *   },\n *   perform: async ({ recipient, body }) => {\n *     return { sent: true };\n *   },\n * });\n * ```\n */\nexport function defineIntent<\n  TParams extends Record<string, ReturnType<(typeof param)[keyof typeof param]>>,\n>(config: IntentDefinition<TParams>): IntentDefinition<TParams> {\n  return config;\n}\n\n// ─── Entity Definition ──────────────────────────────────────────────\n\n/** Display representation mapping for an entity. */\nexport interface EntityDisplay {\n  title: string;\n  subtitle?: string;\n  image?: string;\n}\n\n/** The full entity definition for generating an AppEntity struct. */\nexport interface EntityDefinition {\n  /** PascalCase name for the generated Swift struct. */\n  name: string;\n  /** How the entity is displayed in Siri/Shortcuts. */\n  display: EntityDisplay;\n  /** Entity properties using `param.*` helpers. */\n  properties: Record<string, ReturnType<(typeof param)[keyof typeof param]>>;\n  /** Query type: \"string\" for StringQuery, \"property\" for PropertyQuery. */\n  query?: \"string\" | \"property\";\n}\n\n/**\n * Define an Apple AppEntity for compilation to Swift.\n *\n * Generates a Swift `AppEntity` struct with `EntityQuery` conformance,\n * display representation, and typed properties.\n *\n * @param config - The entity definition\n * @returns The same config (identity function for type inference)\n */\nexport function defineEntity(config: EntityDefinition): EntityDefinition {\n  return config;\n}\n"],"mappings":";AA0DA,SAAS,KAAuB,MAA0B;AACxD,SAAO,CAAC,aAAa,YAAY;AAAA,IAC/B;AAAA,IACA;AAAA,IACA,GAAG;AAAA,EACL;AACF;AAkCO,IAAM,QAAQ;AAAA;AAAA,EAEnB,QAAQ,KAAK,QAAQ;AAAA;AAAA,EAErB,KAAK,KAAK,KAAK;AAAA;AAAA,EAEf,QAAQ,KAAK,QAAQ;AAAA;AAAA,EAErB,OAAO,KAAK,OAAO;AAAA;AAAA,EAEnB,SAAS,KAAK,SAAS;AAAA;AAAA,EAEvB,MAAM,KAAK,MAAM;AAAA;AAAA,EAEjB,UAAU,KAAK,UAAU;AAAA;AAAA,EAEzB,KAAK,KAAK,KAAK;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOf,QAAQ,KAAK,QAAQ;AAAA;AAAA;AAAA;AAAA;AAAA,EAMrB,QAAQ,CAAC,YAAoB,aAAqB,YAAmC;AAAA,IACnF,MAAM;AAAA,IACN;AAAA,IACA;AAAA,IACA,GAAG;AAAA,EACL;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,gBAAgB,CACd,cACA,eACG;AACH,UAAM,EAAE,MAAM,WAAW,aAAa,GAAG,KAAK,IAAI;AAClD,WAAO;AAAA,MACL,MAAM;AAAA,MACN;AAAA,MACA;AAAA,MACA;AAAA,MACA,GAAG;AAAA,IACL;AAAA,EACF;AACF;AA2EO,SAAS,aAEd,QAA8D;AAC9D,SAAO;AACT;AAgCO,SAAS,aAAa,QAA4C;AACvE,SAAO;AACT;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axintai/compiler",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "publishConfig": {
     "access": "public"
   },