zeus-time 0.1.3 → 0.2.2

package/LICENSE

@@ -2,22 +2,6 @@
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
 
-      Copyright 2025 Drew Gardiner aka o0CroMag0o - TIMESync38
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
-
-
-
    TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
    1. Definitions.
@@ -191,3 +175,27 @@
 
    END OF TERMS AND CONDITIONS
 
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,155 +1,201 @@
-# ZEUS: The Future of Timekeeping 🚀
+# ZEUS-Time
 
-**UNIX is dead. ZEUS lives.** This package introduces a deterministic, cryptographically verifiable time system designed to replace traditional UNIX timestamps. With ZEUS, developers can generate and validate time hashes, ensuring synchronization across systems without relying on sequential UNIX time.
+**Deterministic. Verifiable. Calm.**
 
----
+ZEUS-Time is a verifiable time primitive for distributed systems. It
+does not replace clocks. It does not guess truth. It produces
+deterministic, cryptographically verifiable receipts of time.
 
-## 🌟 Features
+Unix time is treated as input material, not authority.
 
-👉 **Deterministic Timestamps** – Generate a unique, cryptographic hash from any timestamp.  
-👉 **Epoch-Based Execution** – Set an epoch based on a ZEUS hash for synchronized execution.  
-👉 **Decentralized & Immutable** – No single point of failure; timestamp verification is trustless.  
-👉 **Backward-Compatible with UNIX** – Convert traditional UNIX time into ZEUS easily.  
-👉 **Supports Legacy Systems** – SHA-256 fallback for older systems that can't run Blake3.  
-👉 **Ideal for Web3, Smart Contracts, IoT, and Security Applications**  
+------------------------------------------------------------------------
 
----
+## What ZEUS Is (and Is Not)
 
-## 🛢️ Installation
+ZEUS provides verifiable ordering and integrity of time-based events.
 
-```sh
-# Using Yarn
-yarn add zeus-time
+-   It proves when something happened relative to other events
+-   It does not claim civil time accuracy
+-   It does not reverse hashes
+-   It does not depend on blockchains or consensus
+
+Think of ZEUS as a time receipt, not a clock.
+
+------------------------------------------------------------------------
+
+## Features
+
+-   Deterministic time hashing using BLAKE3
+-   Stable, reproducible outputs across platforms
+-   Local-first, no network dependency
+-   Expo and React Native compatible
+-   Legacy helpers for smooth migration from 0.1.x
+-   Optional base64url or hex encoding
+-   Explicit separation between time representation and hashing
 
-# Using NPM
+------------------------------------------------------------------------
+
+## Installation
+
+``` sh
 npm install zeus-time
 ```
 
----
+or
+
+``` sh
+yarn add zeus-time
+```
+
+------------------------------------------------------------------------
+
+## Basic Usage
 
-## ❤️ Usage
+### Generate a ZEUS hash from a timestamp
 
-### 🔹 Generate a ZEUS Timestamp
-```typescript
-import { generateZeusHash } from "zeus-time";
+``` ts
+import { zeusHash } from "zeus-time";
 
-async function generateTimeHash() {
-  const timestamp = new Date().toISOString();
-  const hash = await generateZeusHash(timestamp);
-  console.log(`ZEUS Time Hash: ${hash}`);
-}
+const iso = new Date().toISOString();
+const hash = zeusHash(iso);
 
-generateTimeHash();
+console.log(hash);
 ```
 
-### 🔹 Convert UNIX Time to ZEUS Time
-```typescript
-import { unixToZeus } from "zeus-time";
+This hash is deterministic. The same input always produces the same
+output.
 
-const unixTime = Math.floor(Date.now() / 1000);
-unixToZeus(unixTime).then(hash => {
-  console.log(`Converted ZEUS Epoch: ${hash}`);
-});
+------------------------------------------------------------------------
+
+### Stamp unix time deterministically (sync)
+
+``` ts
+import { unixToZeusSync } from "zeus-time";
+
+const unixSeconds = Math.floor(Date.now() / 1000);
+const hash = unixToZeusSync(unixSeconds);
 ```
 
-### 🔹 Convert ZEUS Back to UNIX Time
-```typescript
-import { zeusToUnix } from "zeus-time";
+This is the preferred hot path for applications.
+
+------------------------------------------------------------------------
 
-const zeusHash = "your_zeus_hash_here";
-const unixTime = zeusToUnix(zeusHash);
-console.log(`Converted UNIX Time: ${unixTime}`);
+### Async compatibility helper (legacy friendly)
+
+``` ts
+import { unixToZeus } from "zeus-time";
+
+const hash = await unixToZeus(1704067200);
 ```
+
+This exists for continuity with earlier versions.
+
+------------------------------------------------------------------------
+
+## Verification
+
+### Verify a timestamp against a hash
+
+``` ts
+import { verifyZeusHash } from "zeus-time";
+
+const ok = verifyZeusHash(iso, hash);
 ```
-💡 **Note:** `zeusToUnix()` is the primary function for ZEUS time handling. For legacy support, use `legacyZeusToUnix()`.
+
+Returns true if the hash matches the normalized timestamp.
+
+------------------------------------------------------------------------
+
+### Safe validation helper
+
+``` ts
+import { validateZeusTimestamp } from "zeus-time";
+
+const isValid = await validateZeusTimestamp(iso, hash);
 ```
 
-### 🔹 Execute Based on a ZEUS Epoch
-```typescript
+This helper never throws. It returns false on invalid input.
+
+------------------------------------------------------------------------
+
+## Epoch-Based Execution
+
+``` ts
 import { executeAtZeusEpoch } from "zeus-time";
 
 executeAtZeusEpoch(1735689600, () => {
-  console.log("Executing synchronized action at ZEUS Epoch!");
+  console.log("ZEUS epoch reached");
 });
 ```
 
----
+------------------------------------------------------------------------
 
-## 🚀 Benchmark Performance
-Zeus-Time is **blazing fast!** Recent tests show it can **hash timestamps at record-breaking speeds!** 💥
+## Legacy Compatibility
 
-```bash
-Performance Test: Hashed 1000 timestamps in **12ms** ⚡  
-Performance Test: Hashed 5000 timestamps in **51ms** ⚡  
-Performance Test: Hashed 10,000 timestamps in **98ms** ⚡  
-Performance Test: Hashed 50,000 timestamps in **434ms** ⚡  
-```
+ZEUS 0.2.x keeps compatibility helpers while preserving one-way
+integrity.
 
-### **Why Use Zeus-Time?**
-👉 **Ultra-Fast** - Outperforms traditional UNIX-based hashing.  
-👉 **Cryptographically Secure** - Uses BLAKE3 hashing for reliability.  
-👉 **Future-Proof** - Designed for next-gen blockchain & AI applications.  
+### Legacy hashing helpers
 
----
+``` ts
+import { legacyUnixToZeus, legacyZeusHash } from "zeus-time";
+```
 
-## 🎯 Use Cases
+### Legacy unix conversion
 
-👉 **Smart Contracts** – Ensure execution only happens at a predetermined time.  
-👉 **Decentralized Networks** – Nodes validate time-sensitive actions without a global clock.  
-👉 **Gaming & AI** – Sync in-game events or AI processes based on immutable time hashes.  
-👉 **Supply Chain & IoT** – Devices validate time-based triggers securely.  
-👉 **File Integrity & Authentication** – Timestamped events are cryptographically secured.  
+``` ts
+import { legacyZeusToUnix } from "zeus-time";
+```
 
----
+-   If the input looks like an ISO timestamp, it is parsed
+-   If the input looks like a hash, it throws
+-   Hashes remain one-way by design
 
-## 🔄 Legacy System Support
+------------------------------------------------------------------------
 
-ZEUS is designed for modern timekeeping but also supports **legacy systems** with SHA-256 hashing. If Blake3 is unavailable, ZEUS will fall back to SHA-256, ensuring compatibility across older infrastructures.
+## Performance
 
-🏢 **Legacy Function Naming:**  
-- `legacyUnixToZeus()` → Converts UNIX to ZEUS hash using SHA-256.  
-- `legacyZeusToUnix()` → Attempts UNIX conversion but is not cryptographically reversible.  
+ZEUS is fast enough to be boring.
 
----
+Example benchmarks on a standard desktop:
 
-## 🤡 Test Results
+1,000 hashes \~12 ms 5,000 hashes \~51 ms 10,000 hashes \~98 ms 50,000
+hashes \~430 ms
 
-ZEUS has passed all unit tests for functionality, security, and legacy compatibility.
+------------------------------------------------------------------------
 
-👉 10/10 Tests Passed  
-👉 Validates timestamps correctly (Ensures input is formatted and normalized properly)  
-👉 Ensures deterministic hashing (Same input always produces the same secure hash)  
-👉 Supports legacy SHA-256 fallback (Ensures compatibility with older systems if BLAKE3 is unavailable)  
-👉 Prevents invalid time manipulation (Rejects malformed, tampered, or unrealistic timestamps)  
-👉 Ensures consistent hash output across formats (Tests Date objects, ISO strings, and UNIX timestamps)  
-👉 Handles extreme dates correctly (Validates UNIX epoch and future dates like 2999-12-31)  
-👉 Rejects invalid inputs (Throws errors for undefined, null, and malformed timestamps)  
-👉 Performance benchmark confirmed (**1000 hashes computed in 12ms**)  
+## Use Cases
 
-Run tests yourself:
+-   Audit receipts and compliance logs
+-   Distributed systems needing ordering guarantees
+-   Event integrity verification
+-   Local-first applications
+-   Smart contract preparation and off-chain proofs
+-   Time-bound unlocks and delayed execution
 
-```sh
-yarn test
-```
+ZEUS provides proof of time, not surveillance.
 
----
+------------------------------------------------------------------------
 
-## 🔒 Security & Trust
+## Versioning Strategy
 
-ZEUS ensures **time integrity** without requiring a centralized authority. Hashes are **tamper-proof** and **deterministically generated**, making it impossible to predict or manipulate timestamps in advance.
+-   0.1.x is the stable legacy line
+-   0.2.x clarifies semantics and adds Expo compatibility
+-   latest remains conservative
+-   New behavior is opt-in
 
----
+------------------------------------------------------------------------
 
-## 💚 License
+## License
 
-Licensed under **Apache 2.0**, ensuring open-source innovation while protecting integrity.
+Apache 2.0 Open, boring, and dependable.
 
----
+------------------------------------------------------------------------
 
-## 🚀 Join the Revolution
+## A Small Amount of Fire
 
-**UNIX is outdated. ZEUS is the future.**  
-Get started today and be part of the next evolution in timekeeping!
+Unix time still works. But it was never designed to be verifiable.
 
-LFCROOOOOOO!!!!  🔥⚡
+ZEUS does not replace the clock. It replaces the argument.
 
+BAM!