cloudflare-ddns-sync 4.0.0-beta.2 → 4.0.0-rc.2

package/dist/lib/cloudflare-client.js

@@ -1,158 +1,110 @@
 import { ParseResultType, fromUrl, parseDomain } from 'parse-domain';
 import Cloudflare from 'cloudflare';
-import IPUtils from './ip-utils.js';
-const ipv4Regex = /^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$/u;
-const ipv6Regex = /^(?:(?:(?:(?:(?:(?:(?:[0-9a-fA-F]{1,4})):){6})(?:(?:(?:(?:(?:[0-9a-fA-F]{1,4})):(?:(?:[0-9a-fA-F]{1,4})))|(?:(?:(?:(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9]))\.){3}(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9])))))))|(?:(?:::(?:(?:(?:[0-9a-fA-F]{1,4})):){5})(?:(?:(?:(?:(?:[0-9a-fA-F]{1,4})):(?:(?:[0-9a-fA-F]{1,4})))|(?:(?:(?:(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9]))\.){3}(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9])))))))|(?:(?:(?:(?:(?:[0-9a-fA-F]{1,4})))?::(?:(?:(?:[0-9a-fA-F]{1,4})):){4})(?:(?:(?:(?:(?:[0-9a-fA-F]{1,4})):(?:(?:[0-9a-fA-F]{1,4})))|(?:(?:(?:(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9]))\.){3}(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9])))))))|(?:(?:(?:(?:(?:(?:[0-9a-fA-F]{1,4})):){0,1}(?:(?:[0-9a-fA-F]{1,4})))?::(?:(?:(?:[0-9a-fA-F]{1,4})):){3})(?:(?:(?:(?:(?:[0-9a-fA-F]{1,4})):(?:(?:[0-9a-fA-F]{1,4})))|(?:(?:(?:(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9]))\.){3}(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9])))))))|(?:(?:(?:(?:(?:(?:[0-9a-fA-F]{1,4})):){0,2}(?:(?:[0-9a-fA-F]{1,4})))?::(?:(?:(?:[0-9a-fA-F]{1,4})):){2})(?:(?:(?:(?:(?:[0-9a-fA-F]{1,4})):(?:(?:[0-9a-fA-F]{1,4})))|(?:(?:(?:(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9]))\.){3}(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9])))))))|(?:(?:(?:(?:(?:(?:[0-9a-fA-F]{1,4})):){0,3}(?:(?:[0-9a-fA-F]{1,4})))?::(?:(?:[0-9a-fA-F]{1,4})):)(?:(?:(?:(?:(?:[0-9a-fA-F]{1,4})):(?:(?:[0-9a-fA-F]{1,4})))|(?:(?:(?:(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9]))\.){3}(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9])))))))|(?:(?:(?:(?:(?:(?:[0-9a-fA-F]{1,4})):){0,4}(?:(?:[0-9a-fA-F]{1,4})))?::)(?:(?:(?:(?:(?:[0-9a-fA-F]{1,4})):(?:(?:[0-9a-fA-F]{1,4})))|(?:(?:(?:(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9]))\.){3}(?:(?:25[0-5]|(?:[1-9]|1[0-9]|2[0-4])?[0-9])))))))|(?:(?:(?:(?:(?:(?:[0-9a-fA-F]{1,4})):){0,5}(?:(?:[0-9a-fA-F]{1,4})))?::)(?:(?:[0-9a-fA-F]{1,4})))|(?:(?:(?:(?:(?:(?:[0-9a-fA-F]{1,4})):){0,6}(?:(?:[0-9a-fA-F]{1,4})))?::))))$/u;
+import { isIP } from 'node:net';
+import { SyncError } from './sync-error.js';
 export default class CloudflareClient {
     cloudflare;
     zoneMap = new Map();
-    constructor(cloudflareOptions) {
-        this.cloudflare = new Cloudflare(cloudflareOptions);
-        this.updateZoneMap();
-    }
-    async syncRecord(record, ip) {
-        const recordIds = await this.getRecordIdsForRecords([record]);
-        const ipToUse = ip ? ip : await IPUtils.getIpv4();
-        const zoneId = await this.getZoneIdByRecordName(record.name);
-        const recordId = recordIds.get(this.getRecordIdMapKey(record));
-        const recordExists = recordId !== undefined;
-        if (recordExists) {
-            const result = await this.updateRecord(zoneId, recordId, record, ipToUse);
-            return result;
-        }
-        const result = await this.createRecord(zoneId, record, ipToUse);
-        return result;
+    constructor(auth) {
+        const isUserServiceKey = auth.key?.startsWith('v1.0-');
+        this.cloudflare = new Cloudflare({
+            apiEmail: auth.key && !isUserServiceKey ? (auth.email ?? null) : null,
+            apiKey: !isUserServiceKey ? auth.key || null : null,
+            apiToken: auth.key ? null : auth.token || null,
+            userServiceKey: isUserServiceKey ? auth.key : null,
+            timeout: 10_000,
+        });
     }
-    async syncRecords(records, ip) {
-        const recordIds = await this.getRecordIdsForRecords(records);
-        const ipToUse = ip ? ip : await IPUtils.getIpv4();
-        const resultPromises = records.map(async (record) => {
+    async syncRecords(records) {
+        const existingRecords = await this.getRecordDataForRecords(records);
+        const existingByKey = new Map(existingRecords.map((record) => [this.getRecordIdMapKey(record), record]));
+        const settled = await Promise.allSettled(records.map(async (record) => {
             const zoneId = await this.getZoneIdByRecordName(record.name);
-            const recordId = recordIds.get(this.getRecordIdMapKey(record));
-            const recordExists = recordId !== undefined;
-            if (recordExists) {
-                const currentResult = await this.updateRecord(zoneId, recordId, record, ipToUse);
-                return currentResult;
+            const existing = existingByKey.get(this.getRecordIdMapKey(record));
+            if (existing && this.isUnchanged(existing, record)) {
+                return existing;
+            }
+            return existing ? this.updateRecord(zoneId, existing.id, record) : this.createRecord(zoneId, record);
+        }));
+        const succeeded = [];
+        const failed = [];
+        for (const [index, result] of settled.entries()) {
+            if (result.status === 'fulfilled') {
+                succeeded.push(result.value);
             }
-            const currentResult = await this.createRecord(zoneId, record, ipToUse);
-            return currentResult;
+            else {
+                failed.push({ record: records[index], error: toError(result.reason) });
+            }
+        }
+        if (failed.length > 0) {
+            throw new SyncError(succeeded, failed);
+        }
+        return succeeded;
+    }
+    async planRecords(records) {
+        const existingRecords = await this.getRecordDataForRecords(records);
+        const existingByKey = new Map(existingRecords.map((record) => [this.getRecordIdMapKey(record), record]));
+        return records.map((record) => {
+            const before = existingByKey.get(this.getRecordIdMapKey(record));
+            return { record, before, after: record, action: before ? (this.isUnchanged(before, record) ? 'unchanged' : 'update') : 'create' };
         });
-        const results = await Promise.all(resultPromises);
-        return results;
     }
-    async removeRecordByNameAndType(recordName, recordType) {
-        const recordTypeToUse = recordType ? recordType : 'A';
+    async removeRecordByNameAndType(recordName, recordType = 'A') {
         const zoneId = await this.getZoneIdByRecordName(recordName);
-        const recordId = await this.getRecordIdByNameAndType(recordName, recordTypeToUse);
+        const recordId = await this.getRecordIdByNameAndType(recordName, recordType);
         await this.cloudflare.dns.records.delete(recordId, { zone_id: zoneId });
     }
-    async getRecordDataForRecord(record) {
-        const domain = this.getDomainByRecordName(record.name);
-        const recordDataForDomain = await this.getRecordsByDomain(domain);
-        const recordData = recordDataForDomain.find((singleRecordData) => record.name.toLowerCase() === singleRecordData.name.toLowerCase());
-        return recordData;
-    }
     async getRecordDataForRecords(records) {
-        const domains = this.getDomainsFromRecords(records);
-        const recordDataPromises = domains.map(async (domain) => {
-            const recordDataForDomain = await this.getRecordsByDomain(domain);
-            const recordDataForDomainFilteredByRecords = recordDataForDomain.filter((singleRecordData) => records.some((record) => record.name.toLowerCase() === singleRecordData.name.toLowerCase()));
-            return recordDataForDomainFilteredByRecords;
-        });
-        const recordDataForDomains = await Promise.all(recordDataPromises);
-        const recordData = [].concat(...recordDataForDomains);
-        return recordData;
-    }
-    async getRecordsByDomains(domains) {
-        const recordDataPromises = domains.map((domain) => this.getRecordsByDomain(domain));
-        const recordDataForDomains = await Promise.all(recordDataPromises);
-        const recordData = {};
-        recordDataForDomains.forEach((recordDataForDomain, index) => {
-            recordData[domains[index]] = recordDataForDomain;
-        });
-        return recordData;
-    }
-    async getRecordsByDomain(domain) {
-        const zoneId = await this.getZoneIdByDomain(domain);
-        const allRecords = [];
-        for await (const recordListResponse of this.cloudflare.dns.records.list({ zone_id: zoneId })) {
-            allRecords.push(recordListResponse);
-        }
-        return allRecords;
-    }
-    async createRecord(zoneId, recordData, ip) {
-        const dnsRecordToCreate = {
-            ...recordData,
-            name: recordData.name.toLowerCase(),
-            content: (recordData.content ? recordData.content : ip),
-            type: (recordData.type ? recordData.type : 'A'),
-            ttl: recordData.ttl ? recordData.ttl : 1,
-            zone_id: zoneId,
+        const recordsByDomain = await Promise.all(this.getDomainsFromRecords(records).map((domain) => this.getRecordsByDomain(domain)));
+        return recordsByDomain
+            .flat()
+            .filter((record) => records.some((requestedRecord) => requestedRecord.name.toLowerCase() === record.name.toLowerCase() && (requestedRecord.type === undefined || requestedRecord.type === record.type)));
+    }
+    async getRecordDataForDomains(domains) {
+        const recordsByDomain = await Promise.all(domains.map(async (domain) => [domain, await this.getRecordDataForDomain(domain)]));
+        return Object.fromEntries(recordsByDomain);
+    }
+    getRecordDataForDomain(domain) {
+        return this.getRecordsByDomain(domain);
+    }
+    async createRecord(zoneId, record) {
+        const dnsRecord = this.prepareRecord(record);
+        const response = await this.cloudflare.dns.records.create({ zone_id: zoneId, ...dnsRecord });
+        return response;
+    }
+    async updateRecord(zoneId, recordId, record) {
+        const dnsRecord = this.prepareRecord(record);
+        const response = await this.cloudflare.dns.records.update(recordId, { zone_id: zoneId, ...dnsRecord });
+        return response;
+    }
+    prepareRecord(record) {
+        const dnsRecord = {
+            ...record,
+            name: record.name.toLowerCase(),
+            content: record.content || '',
+            type: record.type || 'A',
+            ttl: record.ttl || 1,
         };
-        if (!dnsRecordToCreate.content) {
-            throw Error(`Could not create Record "${dnsRecordToCreate.name}": Content is missing!`);
+        if (!dnsRecord.content) {
+            throw Error(`Could not sync record "${dnsRecord.name}": content is missing.`);
         }
-        if (dnsRecordToCreate.type === 'A') {
-            if (!dnsRecordToCreate.content.match(ipv4Regex)) {
-                throw Error(`Could not create Record "${dnsRecordToCreate.name}": '${dnsRecordToCreate.content}' is not a valid ipv4!`);
-            }
+        if (dnsRecord.type === 'A' && isIP(dnsRecord.content) !== 4) {
+            throw Error(`Could not sync record "${dnsRecord.name}": '${dnsRecord.content}' is not a valid IPv4 address.`);
         }
-        else if (dnsRecordToCreate.type === 'AAAA') {
-            if (!dnsRecordToCreate.content.match(ipv6Regex)) {
-                throw Error(`Could not create Record "${dnsRecordToCreate.name}": '${dnsRecordToCreate.content}' is not a valid ipv6!`);
-            }
+        if (dnsRecord.type === 'AAAA' && isIP(dnsRecord.content) !== 6) {
+            throw Error(`Could not sync record "${dnsRecord.name}": '${dnsRecord.content}' is not a valid IPv6 address.`);
         }
-        else if (dnsRecordToCreate.type === 'CNAME') {
-            const parsedDomain = parseDomain(fromUrl(dnsRecordToCreate.content));
-            if (parsedDomain.type !== ParseResultType.Listed || !parsedDomain.domain) {
-                throw Error(`Could not create Record "${dnsRecordToCreate.name}": '${dnsRecordToCreate.content}' is not a valid domain name!`);
-            }
+        if (dnsRecord.type === 'CNAME' && !this.isValidDomain(dnsRecord.content)) {
+            throw Error(`Could not sync record "${dnsRecord.name}": '${dnsRecord.content}' is not a valid domain name.`);
         }
-        return this.cloudflare.dns.records.create(dnsRecordToCreate);
-    }
-    async updateRecord(zoneId, recordId, recordData, ip) {
-        const updatedDnsRecord = {
-            ...recordData,
-            name: recordData.name.toLowerCase(),
-            content: (recordData.content ? recordData.content : ip),
-            type: (recordData.type ? recordData.type : 'A'),
-            ttl: recordData.ttl ? recordData.ttl : 1,
-            zone_id: zoneId,
-        };
-        if (!updatedDnsRecord.content) {
-            throw Error(`Could not update Record "${updatedDnsRecord.name}": Content is missing!`);
-        }
-        if (updatedDnsRecord.type === 'A') {
-            if (!updatedDnsRecord.content.match(ipv4Regex)) {
-                throw Error(`Could not update Record "${updatedDnsRecord.name}": '${updatedDnsRecord.content}' is not a valid ipv4!`);
-            }
-        }
-        else if (updatedDnsRecord.type === 'AAAA') {
-            if (!updatedDnsRecord.content.match(ipv6Regex)) {
-                throw Error(`Could not update Record "${updatedDnsRecord.name}": '${updatedDnsRecord.content}' is not a valid ipv6!`);
-            }
-        }
-        else if (updatedDnsRecord.type === 'CNAME') {
-            const parsedDomain = parseDomain(fromUrl(updatedDnsRecord.content));
-            if (parsedDomain.type !== ParseResultType.Listed || !parsedDomain.domain) {
-                throw Error(`Could not update Record "${updatedDnsRecord.name}": '${updatedDnsRecord.content}' is not a valid domain name!`);
-            }
-        }
-        return await this.cloudflare.dns.records.edit(recordId, updatedDnsRecord);
+        return dnsRecord;
     }
     async updateZoneMap() {
-        const response = await this.cloudflare.zones.list();
-        let zones = response.result;
-        let nextPageExists = response.hasNextPage();
-        while (nextPageExists) {
-            const nextPageResponse = await response.getNextPage();
-            zones = zones.concat(nextPageResponse.result);
-            nextPageExists = nextPageResponse.hasNextPage();
-        }
-        this.zoneMap = new Map();
-        for (const zone of zones) {
-            this.zoneMap.set(zone.name, zone.id);
+        const zones = new Map();
+        for await (const zone of this.cloudflare.zones.list()) {
+            zones.set(zone.name.toLowerCase(), zone.id);
         }
+        this.zoneMap = zones;
     }
     async getRecordIdByNameAndType(recordName, recordType) {
         const record = await this.getRecordByNameAndType(recordName, recordType);
@@ -163,54 +115,60 @@ export default class CloudflareClient {
         return this.getZoneIdByDomain(domain);
     }
     async getRecordByNameAndType(recordName, recordType) {
-        const domain = this.getDomainByRecordName(recordName);
-        const records = await this.getRecordsByDomain(domain);
-        const record = records.find((currentRecord) => currentRecord.name.toLowerCase() === recordName.toLowerCase() && currentRecord.type.toLowerCase() === recordType.toLowerCase());
-        const recordNotFound = record === undefined;
-        if (recordNotFound) {
+        const records = await this.getRecordsByDomain(this.getDomainByRecordName(recordName));
+        const record = records.find((entry) => entry.name.toLowerCase() === recordName.toLowerCase() && entry.type.toLowerCase() === recordType.toLowerCase());
+        if (!record) {
             throw new Error(`Record '${recordName}' not found.`);
         }
         return record;
     }
-    async getRecordIdsForRecords(records) {
-        const recordIdMap = new Map();
-        const recordData = await this.getRecordDataForRecords(records);
-        for (const record of recordData) {
-            recordIdMap.set(this.getRecordIdMapKey(record), record.id);
-        }
-        return recordIdMap;
+    isUnchanged(existing, desired) {
+        const prepared = this.prepareRecord(desired);
+        return (existing.name.toLowerCase() === prepared.name &&
+            existing.type === prepared.type &&
+            existing.content === prepared.content &&
+            existing.ttl === prepared.ttl &&
+            (desired.proxied === undefined || existing.proxied === desired.proxied));
     }
     getRecordIdMapKey(record) {
-        const recordName = record.name.toLowerCase();
-        const recordType = record.type ? record.type.toLowerCase() : 'a';
-        return `"${recordName}"_"${recordType}"`;
+        return `${record.name.toLowerCase()}\u0000${(record.type || 'A').toLowerCase()}`;
+    }
+    async getRecordsByDomain(domain) {
+        const zoneId = await this.getZoneIdByDomain(domain);
+        const records = [];
+        for await (const record of this.cloudflare.dns.records.list({ zone_id: zoneId, per_page: 5000 })) {
+            records.push(record);
+        }
+        return records;
     }
     async getZoneIdByDomain(domain) {
-        if (this.zoneMap.has(domain)) {
-            const zoneId = this.zoneMap.get(domain.toLowerCase());
+        const normalizedDomain = domain.toLowerCase();
+        let zoneId = this.zoneMap.get(normalizedDomain);
+        if (zoneId) {
             return zoneId;
         }
         await this.updateZoneMap();
-        if (!this.zoneMap.has(domain)) {
-            throw new Error(`Could not find domain '${domain}'. Make sure the domain is set up for your cloudflare account.`);
+        zoneId = this.zoneMap.get(normalizedDomain);
+        if (!zoneId) {
+            throw new Error(`Could not find domain '${normalizedDomain}'. Make sure the domain is set up for your cloudflare account.`);
         }
-        const zoneId = this.zoneMap.get(domain.toLowerCase());
         return zoneId;
     }
     getDomainsFromRecords(records) {
-        const domains = records.map((record) => this.getDomainByRecordName(record.name)).filter((domain, index, domainList) => domainList.indexOf(domain.toLowerCase()) === index);
-        return domains;
+        return [...new Set(records.map((record) => this.getDomainByRecordName(record.name)))];
     }
     getDomainByRecordName(recordName) {
-        const parsedDomain = parseDomain(fromUrl(recordName));
+        const parsedDomain = parseDomain(fromUrl(recordName.replace(/^\*\./, '')));
         if (parsedDomain.type !== ParseResultType.Listed || !parsedDomain.domain) {
             throw new Error(`Could not parse domain. '${JSON.stringify(recordName)}' is not a valid record name.`);
         }
-        let domain = '';
-        domain += parsedDomain.domain;
-        for (const tld of parsedDomain.topLevelDomains) {
-            domain += `.${tld}`;
-        }
-        return domain.toLowerCase();
+        return [parsedDomain.domain, ...parsedDomain.topLevelDomains].join('.').toLowerCase();
     }
+    isValidDomain(value) {
+        const parsedDomain = parseDomain(fromUrl(value));
+        return parsedDomain.type === ParseResultType.Listed && Boolean(parsedDomain.domain);
+    }
+}
+function toError(value) {
+    return value instanceof Error ? value : new Error(String(value));
 }

package/dist/lib/cron.d.ts

@@ -1,5 +1,5 @@
 import { ScheduledTask } from 'node-cron';
 export default class Cron {
-    static createCronJob(cronExpression: string, callback: Function): ScheduledTask;
+    static createCronJob(cronExpression: string, callback: () => void | Promise<void>): ScheduledTask;
     static isValid(cronExpression: string): boolean;
 }

package/dist/lib/cron.js

@@ -5,9 +5,7 @@ export default class Cron {
         if (cronExpressionIsInvalid) {
             throw new Error(`'${cronExpression}' is not a valid cron expression.\nHere you can see how cron expressions work: https://cddnss.knaup.pw/cron-expression-syntax`);
         }
-        return cron.schedule(cronExpression, () => {
-            callback();
-        }, undefined);
+        return cron.schedule(cronExpression, callback);
     }
     static isValid(cronExpression) {
         return cron.validate(cronExpression);

package/dist/lib/ip-utils.d.ts

@@ -1,9 +1,4 @@
 export default class IPUtils {
-    private static readonly ipPollingDelay;
-    private static ipChangeEventListeners;
     static getIpv4(): Promise<string>;
     static getIpv6(): Promise<string>;
-    static addIpChangeListener(callback: Function): Promise<string>;
-    static removeIpChangeListener(eventListenerId: string): void;
-    private static getId;
 }

package/dist/lib/ip-utils.js

@@ -1,7 +1,5 @@
 import { publicIpv4, publicIpv6 } from 'public-ip';
 export default class IPUtils {
-    static ipPollingDelay = 10 * 1000;
-    static ipChangeEventListeners = new Map();
     static async getIpv4() {
         /* c8 ignore start*/
         try {
@@ -22,28 +20,4 @@ export default class IPUtils {
         }
         /* c8 ignore stop*/
     }
-    static async addIpChangeListener(callback) {
-        const eventListenerId = this.getId();
-        let previousIp = await this.getIpv4();
-        /* c8 ignore start */
-        const intervalId = setInterval(async () => {
-            const currentIp = await this.getIpv4();
-            const ipMustBeUpdated = currentIp !== previousIp;
-            if (ipMustBeUpdated) {
-                previousIp = currentIp;
-                callback(currentIp);
-            }
-        }, this.ipPollingDelay);
-        /* c8 ignore stop*/
-        this.ipChangeEventListeners.set(eventListenerId, intervalId);
-        return eventListenerId;
-    }
-    static removeIpChangeListener(eventListenerId) {
-        const eventListenerIntervalId = this.ipChangeEventListeners.get(eventListenerId);
-        clearInterval(eventListenerIntervalId);
-        IPUtils.ipChangeEventListeners.delete(eventListenerId);
-    }
-    static getId() {
-        return Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15);
-    }
 }

package/dist/lib/sync-error.d.ts

@@ -0,0 +1,12 @@
+import { DnsRecord, Record } from '../types/index.js';
+export declare class SyncError extends Error {
+    readonly succeeded: Array<DnsRecord>;
+    readonly failed: Array<{
+        record: Record;
+        error: Error;
+    }>;
+    constructor(succeeded: Array<DnsRecord>, failed: Array<{
+        record: Record;
+        error: Error;
+    }>);
+}

package/dist/lib/sync-error.js

@@ -0,0 +1,10 @@
+export class SyncError extends Error {
+    succeeded;
+    failed;
+    constructor(succeeded, failed) {
+        super('One or more DNS records could not be synchronized.');
+        this.succeeded = succeeded;
+        this.failed = failed;
+        this.name = 'SyncError';
+    }
+}

package/dist/lib/sync-job.d.ts

@@ -0,0 +1,44 @@
+import { DnsRecord, JobOptions, RecordSelection, SyncJob, SyncOptions, WatchOptions } from '../types/index.js';
+export type SyncJobOperations = {
+    sync(records: RecordSelection | undefined, options: SyncOptions): Promise<Array<DnsRecord>>;
+    ip(family: 4 | 6): Promise<string>;
+};
+declare abstract class BaseSyncJob implements SyncJob {
+    protected readonly operations: SyncJobOperations;
+    protected readonly options: JobOptions;
+    private inFlight?;
+    private callingCallback;
+    constructor(operations: SyncJobOperations, options: JobOptions);
+    run(): Promise<Array<DnsRecord>>;
+    abstract start(): Promise<void>;
+    abstract stop(): Promise<void>;
+    protected runInBackground(options?: SyncOptions): void;
+    protected runWith(options: SyncOptions): Promise<Array<DnsRecord>>;
+    protected settle(): Promise<void>;
+    protected reportError(error: Error): Promise<void>;
+    private perform;
+}
+export declare class ScheduledSyncJob extends BaseSyncJob {
+    private readonly task;
+    private active;
+    constructor(operations: SyncJobOperations, expression: string, options: JobOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+export declare class WatchSyncJob extends BaseSyncJob {
+    private readonly watchOptions;
+    private readonly families;
+    private timer?;
+    private active;
+    private starting?;
+    private checking?;
+    private previousAddresses;
+    constructor(operations: SyncJobOperations, watchOptions: WatchOptions, families: Array<4 | 6>);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private startWatcher;
+    private checkInBackground;
+    private checkForChanges;
+    private currentAddresses;
+}
+export {};

package/dist/lib/sync-job.js

@@ -0,0 +1,190 @@
+import Cron from './cron.js';
+const defaultWatchIntervalMs = 10_000;
+class BaseSyncJob {
+    operations;
+    options;
+    inFlight;
+    callingCallback = false;
+    constructor(operations, options) {
+        this.operations = operations;
+        this.options = options;
+    }
+    run() {
+        return this.runWith(this.options);
+    }
+    runInBackground(options = this.options) {
+        void this.runWith(options).catch(async (error) => this.reportError(toError(error)));
+    }
+    runWith(options) {
+        if (this.inFlight) {
+            return this.inFlight;
+        }
+        const run = this.perform(options);
+        this.inFlight = run;
+        void run
+            .finally(() => {
+            if (this.inFlight === run) {
+                this.inFlight = undefined;
+            }
+        })
+            .catch(() => undefined);
+        return run;
+    }
+    async settle() {
+        if (!this.callingCallback) {
+            await this.inFlight?.catch(() => undefined);
+        }
+    }
+    async reportError(error) {
+        try {
+            if (this.options.onError) {
+                await this.options.onError(error);
+            }
+            else {
+                console.error(error);
+            }
+        }
+        catch (callbackError) {
+            console.error(toError(callbackError));
+        }
+    }
+    async perform(options) {
+        const result = await this.operations.sync(this.options.records, options);
+        this.callingCallback = true;
+        try {
+            await this.options.onSync?.(result);
+        }
+        finally {
+            this.callingCallback = false;
+        }
+        return result;
+    }
+}
+export class ScheduledSyncJob extends BaseSyncJob {
+    task;
+    active = true;
+    constructor(operations, expression, options) {
+        super(operations, options);
+        this.task = Cron.createCronJob(expression, () => {
+            if (this.active) {
+                this.runInBackground();
+            }
+        });
+    }
+    async start() {
+        if (!this.active) {
+            this.active = true;
+            await this.task.start();
+        }
+    }
+    async stop() {
+        this.active = false;
+        await this.task.stop();
+        await this.settle();
+    }
+}
+export class WatchSyncJob extends BaseSyncJob {
+    watchOptions;
+    families;
+    timer;
+    active = false;
+    starting;
+    checking;
+    previousAddresses = new Map();
+    constructor(operations, watchOptions, families) {
+        super(operations, watchOptions);
+        this.watchOptions = watchOptions;
+        this.families = families;
+    }
+    start() {
+        if (this.starting) {
+            return this.starting;
+        }
+        if (this.active) {
+            return Promise.resolve();
+        }
+        this.active = true;
+        const start = this.startWatcher();
+        this.starting = start;
+        void start.finally(() => {
+            if (this.starting === start) {
+                this.starting = undefined;
+            }
+        });
+        return start;
+    }
+    async stop() {
+        this.active = false;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        await this.checking?.catch(() => undefined);
+        await this.settle();
+    }
+    async startWatcher() {
+        const addresses = await this.currentAddresses();
+        if (!this.active) {
+            return;
+        }
+        await this.runWith({ ...this.options, ...addressesToOptions(addresses) });
+        if (!this.active) {
+            return;
+        }
+        this.previousAddresses = addresses;
+        if (this.families.length > 0) {
+            this.timer = setInterval(() => {
+                this.checkInBackground();
+            }, this.watchOptions.intervalMs ?? defaultWatchIntervalMs);
+        }
+    }
+    checkInBackground() {
+        if (!this.active || this.checking) {
+            return;
+        }
+        const check = this.checkForChanges();
+        this.checking = check;
+        void check
+            .catch(async (error) => this.reportError(toError(error)))
+            .finally(() => {
+            if (this.checking === check) {
+                this.checking = undefined;
+            }
+        });
+    }
+    async checkForChanges() {
+        const addresses = await this.currentAddresses();
+        if (!this.active || !addressesChanged(this.previousAddresses, addresses)) {
+            return;
+        }
+        await this.runWith({ ...this.options, ...addressesToOptions(addresses) });
+        if (this.active) {
+            this.previousAddresses = addresses;
+        }
+    }
+    async currentAddresses() {
+        const addresses = new Map();
+        await Promise.all(this.families.map(async (family) => {
+            addresses.set(family, await this.operations.ip(family));
+        }));
+        return addresses;
+    }
+}
+function addressesToOptions(addresses) {
+    const options = {};
+    const ipv4 = addresses.get(4);
+    const ipv6 = addresses.get(6);
+    if (ipv4) {
+        options.ipv4 = ipv4;
+    }
+    if (ipv6) {
+        options.ipv6 = ipv6;
+    }
+    return options;
+}
+function addressesChanged(previous, current) {
+    return previous.size !== current.size || [...current].some(([family, address]) => previous.get(family) !== address);
+}
+function toError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}