🤖 Merge PR DefinitelyTyped#73762 [spf-parse] Add types for spf-parse by @ultraslayyy

Co-authored-by: Adam Thompson-Sharpe <[email protected]>

Author: ultraslayyy

types/spf-parse/.npmignore

@@ -0,0 +1,5 @@
+*
+!**/*.d.ts
+!**/*.d.cts
+!**/*.d.mts
+!**/*.d.*.ts

types/spf-parse/index.d.ts

@@ -0,0 +1,76 @@
+export = spfParse;
+
+declare namespace spfParse {
+    /** Qualifer prefix characters */
+    type Prefix = '+' | '-' | '~' | '?' | 'v';
+
+    /** Prefix descriptions */
+    interface PrefixDescriptions {
+        '+': 'Pass';
+        '-': 'Fail';
+        '~': 'SoftFail';
+        '?': 'Neutral';
+        v?: string;
+    }
+
+    /** A single parsed SPF mechanism */
+    interface Mechanism {
+        /** Mechanism type, e.g. 'ip4', 'mx', 'all' */
+        type: string;
+
+        /** Optional value associated with the mechanism (domain, IP, etc.) */
+        value?: string;
+
+        /** The qualifier prefix */
+        prefix: Prefix;
+
+        /** Human-readable description of the prefix */
+        prefixdesc?: string;
+
+        /** Human-readable description of the mechanism */
+        description?: string;
+    }
+
+    /** Parse message (warning or error) */
+    interface ParseMessage {
+        /** Text of the message */
+        message: string;
+
+        /** Message type: error or warning */
+        type: 'error' | 'warning';
+    }
+
+    /** Result of parsing a single SPF record */
+    interface ParseResult {
+        /** Parsed mechanisms */
+        mechanisms: Mechanism[];
+
+        /** Validation messages */
+        messages?: ParseMessage[];
+
+        /** True if record parsed successfully */
+        valid: boolean;
+    }
+
+    /** Error thrown by mechanism validators */
+    class MechanismError extends Error {
+        /** Error type */
+        type: 'warning' | 'error';
+        constructor(message: string, type?: 'warning' | 'error');
+    }
+
+    /**
+     * Parse a single SPF term (e.g. "+ip4:192.0.2.0/24")
+     * @param term SPF term string
+     * @param messages Message array to push validation errors/warnings into
+     * @returns Parsed mechanism record
+     */
+    function parseTerm(term: string, messages: ParseMessage[]): Mechanism;
+}
+
+/**
+ * Parse a full SPF record string (e.g. "v=spf1 include:some.sender.org -all")
+ * @param record SPF record string
+ * @returns Structured parse result
+ */
+declare function spfParse(record: string): spfParse.ParseResult;

types/spf-parse/package.json

@@ -0,0 +1,17 @@
+{
+    "private": true,
+    "name": "@types/spf-parse",
+    "version": "1.0.9999",
+    "projects": [
+        "https://github.com/softvu/spf-parse#readme"
+    ],
+    "devDependencies": {
+        "@types/spf-parse": "workspace:."
+    },
+    "owners": [
+        {
+            "name": "ultraslayyy",
+            "githubUsername": "ultraslayyy"
+        }
+    ]
+}

types/spf-parse/spf-parse-tests.ts

@@ -0,0 +1,26 @@
+import spfParse = require('spf-parse');
+
+const result = spfParse('v=spf1 a mx -all'); // $ExpectType ParseResult
+result.mechanisms; // $ExpectType Mechanism[]
+result.valid; // $ExpectType boolean
+
+for (const mech of result.mechanisms) {
+    mech.type; // $ExpectType string
+    mech.value; // $ExpectType string | undefined
+    mech.prefix; // $ExpectType Prefix
+    mech.prefixdesc; // $ExpectType string | undefined
+    mech.description; // $ExpectType string | undefined
+}
+
+if (result.messages) {
+    for (const msg of result.messages) {
+        msg.message; // $ExpectType string
+        msg.type; // $ ExpectType "error" | "warning"
+    }
+}
+
+const messages: spfParse.ParseMessage[] = [];
+const mech = spfParse.parseTerm('ip4:192.0.2.0/24', messages); // $ExpectType Mechanism
+
+const err = new spfParse.MechanismError('invalid mech', 'error'); // $ExpectType MechanismError
+err.type; // $ExpectType "warning" | "error"

types/spf-parse/tsconfig.json

@@ -0,0 +1,19 @@
+{
+    "compilerOptions": {
+        "module": "node16",
+        "lib": [
+            "es6"
+        ],
+        "noImplicitAny": true,
+        "noImplicitThis": true,
+        "strictNullChecks": true,
+        "strictFunctionTypes": true,
+        "types": [],
+        "noEmit": true,
+        "forceConsistentCasingInFileNames": true
+    },
+    "files": [
+        "index.d.ts",
+        "spf-parse-tests.ts"
+    ]
+}