Policies

Declarative replication, encryption, and retention policies for governing data lifecycle.

Overview

Policies are declarative rules that govern how data is stored, replicated, and retained. Instead of scattering configuration across your application code, you define policies in persist.config.ts and Persist enforces them automatically.

Replication policies

Replication policies control which stores sync to which remotes and how frequently.

// persist.config.ts
export default {
  stores: {
    tasks: {
      replication: {
        targets: ["https://sync.persist.one"],
        interval: 10_000,    // sync every 10 seconds
        batchSize: 100,      // max operations per push
        filter: (record) => !record.value.draft, // skip drafts
      },
    },
  },
};

You can configure different replication targets for different stores. A high-frequency store like real-time collaboration might sync every second, while a settings store syncs every minute.

Encryption policies

Encryption policies define which stores are encrypted and with what parameters.

export default {
  stores: {
    secrets: {
      encryption: {
        enabled: true,
        algorithm: "aes-256-gcm",
        keyRotationDays: 90,
      },
    },
    logs: {
      encryption: {
        enabled: false, // logs are not encrypted
      },
    },
  },
};

When keyRotationDays is set, Persist emits a key:rotation:due event when the current KEK approaches the rotation threshold. Your application can handle this event to trigger automatic rotation.

Retention policies

Retention policies control how long data is kept and when it is purged.

export default {
  stores: {
    events: {
      retention: {
        maxAge: "90d",     // delete events older than 90 days
        maxCount: 10_000,  // keep at most 10,000 events
        pruneInterval: "1h", // check hourly
      },
    },
  },
};

Retention runs as a background task. When both maxAge and maxCount are set, the stricter limit applies. Pruned records are removed from the local store and marked as tombstones so that sync does not re-introduce them from other devices.

Combining policies

Policies compose naturally. A single store can have replication, encryption, and retention policies applied simultaneously. Persist validates the combination at startup and warns if policies conflict (for example, replicating to an unencrypted remote while the store has encryption enabled).

export default {
  stores: {
    audit: {
      replication: { targets: ["https://sync.persist.one"], interval: 5000 },
      encryption: { enabled: true, algorithm: "aes-256-gcm" },
      retention: { maxAge: "365d" },
    },
  },
};