@tpmjs/official-regex-extract 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 TPMJS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,183 @@
+# @tpmjs/official-regex-extract
+
+Extract all regex matches from text with optional capture group support.
+
+## Installation
+
+```bash
+npm install @tpmjs/official-regex-extract
+```
+
+## Usage
+
+```typescript
+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',
+});
+```
+
+## Parameters
+
+- `text` (string, required): The text to search for matches
+- `pattern` (string, required): Regular expression pattern (without delimiters)
+- `flags` (string, optional): Regular expression flags
+  - `g` - global (automatically added if not present)
+  - `i` - case-insensitive
+  - `m` - multiline
+  - `s` - dotAll (. matches newlines)
+  - `u` - unicode
+  - `y` - sticky
+- `groups` (boolean, optional): If true, return detailed match objects with capture groups and positions. Default: false
+
+## Returns
+
+```typescript
+{
+  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
+}
+```
+
+## Examples
+
+### Extract email addresses
+
+```typescript
+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
+// }
+```
+
+### Extract URLs with capture groups
+
+```typescript
+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
+// }
+```
+
+### Extract phone numbers
+
+```typescript
+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
+// }
+```
+
+### Extract hashtags (case-insensitive)
+
+```typescript
+const result = await regexExtractTool.execute({
+  text: 'Love #JavaScript and #TypeScript!',
+  pattern: '#\\w+',
+  flags: 'i',
+});
+// {
+//   matches: ['#JavaScript', '#TypeScript'],
+//   matchCount: 2,
+//   hasMatches: true
+// }
+```
+
+### Extract dates with named groups
+
+```typescript
+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
+// }
+```
+
+## Use Cases
+
+- Extracting email addresses from text
+- Finding URLs in content
+- Parsing phone numbers
+- Extracting hashtags or mentions
+- Finding dates in various formats
+- Extracting code snippets or code blocks
+- Parsing structured data from text
+- Finding price values
+- Extracting IP addresses
+- Validating and extracting specific patterns
+
+## Tips
+
+- The `g` (global) flag is automatically added to find all matches
+- Use named capture groups `(?<name>...)` for clearer results when `groups=true`
+- Escape special regex characters: `\` `^` `$` `.` `*` `+` `?` `(` `)` `[` `]` `{` `}` `|`
+- Use `i` flag for case-insensitive matching
+- Use `m` flag when matching across multiple lines with `^` and `$`
+
+## Error Handling
+
+The tool throws an error if:
+- The pattern is invalid regex syntax
+- Text or pattern is not a string
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import * as ai from 'ai';
+
+/**
+ * Regex Extract Tool for TPMJS
+ * Extracts all regex matches from text with optional capture group support
+ */
+/**
+ * Input interface for regex extraction
+ */
+interface RegexExtractInput {
+    text: string;
+    pattern: string;
+    flags?: string;
+    groups?: boolean;
+}
+/**
+ * Match object with capture groups
+ */
+interface MatchWithGroups {
+    match: string;
+    groups: Record<string, string | undefined>;
+    index: number;
+}
+/**
+ * Output interface for regex extract result
+ */
+interface RegexExtractResult {
+    matches: string[] | MatchWithGroups[];
+    matchCount: number;
+    hasMatches: boolean;
+}
+/**
+ * Regex Extract Tool
+ * Extracts all matches from text using a regular expression pattern
+ */
+declare const regexExtractTool: ai.Tool<RegexExtractInput, RegexExtractResult>;
+
+export { type RegexExtractResult, regexExtractTool as default, regexExtractTool };

package/dist/index.js

@@ -0,0 +1,69 @@
+import { tool, jsonSchema } from 'ai';
+
+// src/index.ts
+var regexExtractTool = tool({
+  description: "Extract all regex matches from text. Supports regex flags (g, i, m, s, u, y) and optional capture group extraction. Returns all matches with their positions and capture groups if requested. Useful for parsing structured text, extracting patterns, or validating formats.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      text: {
+        type: "string",
+        description: "The text to search for matches"
+      },
+      pattern: {
+        type: "string",
+        description: "Regular expression pattern (without delimiters)"
+      },
+      flags: {
+        type: "string",
+        description: 'Regular expression flags (g=global, i=case-insensitive, m=multiline, s=dotAll, u=unicode, y=sticky). The "g" flag is added automatically if not present.'
+      },
+      groups: {
+        type: "boolean",
+        description: "If true, return matches as objects with capture groups and positions. If false, return simple string array of full matches. (default: false)"
+      }
+    },
+    required: ["text", "pattern"],
+    additionalProperties: false
+  }),
+  execute: async ({ text, pattern, flags = "", groups = false }) => {
+    if (typeof text !== "string") {
+      throw new Error("Text must be a string");
+    }
+    if (typeof pattern !== "string") {
+      throw new Error("Pattern must be a string");
+    }
+    const finalFlags = flags.includes("g") ? flags : flags + "g";
+    try {
+      const regex = new RegExp(pattern, finalFlags);
+      const matchIterator = text.matchAll(regex);
+      const allMatches = Array.from(matchIterator);
+      if (groups) {
+        const matches = allMatches.map((match) => ({
+          match: match[0],
+          groups: match.groups || {},
+          index: match.index ?? 0
+        }));
+        return {
+          matches,
+          matchCount: matches.length,
+          hasMatches: matches.length > 0
+        };
+      } else {
+        const matches = allMatches.map((match) => match[0]);
+        return {
+          matches,
+          matchCount: matches.length,
+          hasMatches: matches.length > 0
+        };
+      }
+    } catch (error) {
+      throw new Error(
+        `Failed to extract regex matches: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+});
+var index_default = regexExtractTool;
+
+export { index_default as default, regexExtractTool };

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@tpmjs/official-regex-extract",
+  "version": "0.1.0",
+  "description": "Extract all regex matches from text with optional capture group support",
+  "type": "module",
+  "keywords": [
+    "tpmjs",
+    "text",
+    "regex",
+    "extract",
+    "pattern",
+    "matching"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.9.3",
+    "@tpmjs/tsconfig": "0.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anthropics/tpmjs.git",
+    "directory": "packages/tools/official/regex-extract"
+  },
+  "homepage": "https://tpmjs.com",
+  "license": "MIT",
+  "tpmjs": {
+    "category": "text",
+    "frameworks": [
+      "vercel-ai"
+    ],
+    "tools": [
+      {
+        "name": "regexExtractTool",
+        "description": "Extract all regex matches from text with optional capture group support",
+        "parameters": [
+          {
+            "name": "text",
+            "type": "string",
+            "description": "The text to search",
+            "required": true
+          },
+          {
+            "name": "pattern",
+            "type": "string",
+            "description": "Regular expression pattern",
+            "required": true
+          },
+          {
+            "name": "flags",
+            "type": "string",
+            "description": "Regular expression flags (g, i, m, s, u, y)",
+            "required": false
+          },
+          {
+            "name": "groups",
+            "type": "boolean",
+            "description": "Return capture groups as objects",
+            "required": false
+          }
+        ],
+        "returns": {
+          "type": "RegexExtractResult",
+          "description": "Object with matches array, match count, and hasMatches flag"
+        }
+      }
+    ]
+  },
+  "dependencies": {
+    "ai": "6.0.0-beta.124"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  }
+}