npm install @tpmjs/official-regex-extract

import { regexExtractTool } from '@tpmjs/official-regex-extract';
import { generateText } from 'ai';

const result = await generateText({
  model: yourModel,
  tools: {
    regexExtract: regexExtractTool,
  },
  prompt: 'Extract all email addresses from the text',
});

{
  matches: string[] | MatchWithGroups[];  // Array of matches
  matchCount: number;                     // Total number of matches
  hasMatches: boolean;                    // Whether any matches were found
}

// When groups=true, each match is:
{
  match: string;                          // The full matched text
  groups: Record<string, string>;         // Named capture groups
  index: number;                          // Position in text
}

const result = await regexExtractTool.execute({
  text: 'Contact us at support@example.com or sales@example.com',
  pattern: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}',
  flags: 'i',
});
// {
//   matches: ['support@example.com', 'sales@example.com'],
//   matchCount: 2,
//   hasMatches: true
// }

const result = await regexExtractTool.execute({
  text: 'Visit https://example.com and http://test.org',
  pattern: '(?<protocol>https?)://(?<domain>[^\\s]+)',
  groups: true,
});
// {
//   matches: [
//     {
//       match: 'https://example.com',
//       groups: { protocol: 'https', domain: 'example.com' },
//       index: 6
//     },
//     {
//       match: 'http://test.org',
//       groups: { protocol: 'http', domain: 'test.org' },
//       index: 30
//     }
//   ],
//   matchCount: 2,
//   hasMatches: true
// }

const result = await regexExtractTool.execute({
  text: 'Call (555) 123-4567 or (555) 987-6543',
  pattern: '\\(\\d{3}\\)\\s\\d{3}-\\d{4}',
});
// {
//   matches: ['(555) 123-4567', '(555) 987-6543'],
//   matchCount: 2,
//   hasMatches: true
// }

const result = await regexExtractTool.execute({
  text: 'Love #JavaScript and #TypeScript!',
  pattern: '#\\w+',
  flags: 'i',
});
// {
//   matches: ['#JavaScript', '#TypeScript'],
//   matchCount: 2,
//   hasMatches: true
// }

const result = await regexExtractTool.execute({
  text: 'Event on 2024-03-15 and deadline 2024-06-30',
  pattern: '(?<year>\\d{4})-(?<month>\\d{2})-(?<day>\\d{2})',
  groups: true,
});
// {
//   matches: [
//     {
//       match: '2024-03-15',
//       groups: { year: '2024', month: '03', day: '15' },
//       index: 9
//     },
//     {
//       match: '2024-06-30',
//       groups: { year: '2024', month: '06', day: '30' },
//       index: 33
//     }
//   ],
//   matchCount: 2,
//   hasMatches: true
// }