@durable-streams/server 0.2.3 → 0.3.1

package/dist/index.d.cts

@@ -57,6 +57,12 @@ interface Stream {
   */
   createdAt: number;
   /**
+  * Timestamp of the last read or write (for TTL renewal).
+  * Initialized to createdAt. Updated on GET reads and POST appends.
+  * HEAD requests do NOT update this field.
+  */
+  lastAccessedAt: number;
+  /**
   * Producer states for idempotent writes.
   * Maps producer ID to their epoch and sequence state.
   */
@@ -75,6 +81,24 @@ interface Stream {
     epoch: number;
     seq: number;
   };
+  /**
+  * Source stream path (set when this stream is a fork).
+  */
+  forkedFrom?: string;
+  /**
+  * Divergence offset from the source stream.
+  * Format: "0000000000000000_0000000000000000"
+  */
+  forkOffset?: string;
+  /**
+  * Number of forks referencing this stream.
+  * Defaults to 0.
+  */
+  refCount: number;
+  /**
+  * Whether this stream is logically deleted but retained for fork readers.
+  */
+  softDeleted?: boolean;
 }
 /**
 * Event data for stream lifecycle hooks.
@@ -251,13 +275,19 @@ declare class StreamStore {
   */
   private isExpired;
   /**
-  * Get a stream, deleting it if expired.
-  * Returns undefined if stream doesn't exist or is expired.
+  * Get a stream, handling expiry.
+  * Returns undefined if stream doesn't exist or is expired (and has no refs).
+  * Expired streams with refCount > 0 are soft-deleted instead of fully deleted.
   */
   private getIfNotExpired;
   /**
+  * Update lastAccessedAt to now. Called on reads and appends (not HEAD).
+  */
+  touchAccess(path: string): void;
+  /**
   * Create a new stream.
   * @throws Error if stream already exists with different config
+  * @throws Error if fork source not found, soft-deleted, or offset invalid
   * @returns existing stream if config matches (idempotent)
   */
   create(path: string, options?: {
@@ -266,21 +296,36 @@ declare class StreamStore {
     expiresAt?: string;
     initialData?: Uint8Array;
     closed?: boolean;
+    forkedFrom?: string;
+    forkOffset?: string;
   }): Stream;
   /**
+  * Resolve fork expiry per the decision table.
+  * Forks have independent lifetimes — no capping at source expiry.
+  */
+  private resolveForkExpiry;
+  /**
   * Get a stream by path.
   * Returns undefined if stream doesn't exist or is expired.
+  * Returns soft-deleted streams (caller should check stream.softDeleted).
   */
   get(path: string): Stream | undefined;
   /**
-  * Check if a stream exists (and is not expired).
+  * Check if a stream exists, is not expired, and is not soft-deleted.
   */
   has(path: string): boolean;
   /**
   * Delete a stream.
+  * If the stream has forks (refCount > 0), it is soft-deleted instead of fully removed.
+  * Returns true if the stream was found and deleted (or soft-deleted).
   */
   delete(path: string): boolean;
   /**
+  * Fully delete a stream and cascade to soft-deleted parents
+  * whose refcount drops to zero.
+  */
+  private deleteWithCascade;
+  /**
   * Validate producer state WITHOUT mutating.
   * Returns proposed state to commit after successful append.
   * Implements Kafka-style idempotent producer validation.
@@ -346,6 +391,7 @@ declare class StreamStore {
   getProducerEpoch(path: string, producerId: string): number | undefined;
   /**
   * Read messages from a stream starting at the given offset.
+  * For forked streams, stitches messages from the source chain and the fork's own messages.
   * @throws Error if stream doesn't exist or is expired
   */
   read(path: string, offset?: string): {
@@ -353,6 +399,20 @@ declare class StreamStore {
     upToDate: boolean;
   };
   /**
+  * Read from a forked stream, stitching inherited and own messages.
+  */
+  private readFromFork;
+  /**
+  * Read a stream's own messages starting after the given offset.
+  */
+  private readOwnMessages;
+  /**
+  * Recursively read messages from a fork's source chain.
+  * Reads from source (and its sources if also forked), capped at forkOffset.
+  * Does NOT check softDeleted — forks must read through soft-deleted sources.
+  */
+  private readForkedMessages;
+  /**
   * Format messages for response.
   * For JSON mode, wraps concatenated data in array brackets.
   * @throws Error if stream doesn't exist or is expired
@@ -450,15 +510,25 @@ declare class FileBackedStreamStore {
   */
   getProducerEpoch(streamPath: string, producerId: string): number | undefined;
   /**
+  * Update lastAccessedAt to now. Called on reads and appends (not HEAD).
+  */
+  touchAccess(streamPath: string): void;
+  /**
   * Check if a stream is expired based on TTL or Expires-At.
   */
   private isExpired;
   /**
   * Get stream metadata, deleting it if expired.
-  * Returns undefined if stream doesn't exist or is expired.
+  * Returns undefined if stream doesn't exist or is expired (and has no refs).
+  * Expired streams with refCount > 0 are soft-deleted instead of fully deleted.
   */
   private getMetaIfNotExpired;
   /**
+  * Resolve fork expiry per the decision table.
+  * Forks have independent lifetimes — no capping at source expiry.
+  */
+  private resolveForkExpiry;
+  /**
   * Close the store, closing all file handles and database.
   * All data is already fsynced on each append, so no final flush needed.
   */
@@ -469,10 +539,17 @@ declare class FileBackedStreamStore {
     expiresAt?: string;
     initialData?: Uint8Array;
     closed?: boolean;
+    forkedFrom?: string;
+    forkOffset?: string;
   }): Promise<Stream>;
   get(streamPath: string): Stream | undefined;
   has(streamPath: string): boolean;
   delete(streamPath: string): boolean;
+  /**
+  * Fully delete a stream and cascade to soft-deleted parents
+  * whose refcount drops to zero.
+  */
+  private deleteWithCascade;
   append(streamPath: string, data: Uint8Array, options?: AppendOptions & {
     isInitialCreate?: boolean;
   }): Promise<StreamMessage | AppendResult | null>;
@@ -503,6 +580,21 @@ declare class FileBackedStreamStore {
     alreadyClosed: boolean;
     producerResult?: ProducerValidationResult;
   } | null>;
+  /**
+  * Read messages from a specific segment file.
+  * @param segmentPath - Path to the segment file
+  * @param startByte - Start byte offset (skip messages at or before this offset)
+  * @param baseByteOffset - Base byte offset to add to physical offsets (for fork stitching)
+  * @param capByte - Optional cap: stop reading when logical offset exceeds this value
+  * @returns Array of messages with properly computed offsets
+  */
+  private readMessagesFromSegmentFile;
+  /**
+  * Recursively read messages from a fork's source chain.
+  * Reads from source (and its sources if also forked), capped at capByte.
+  * Does NOT check softDeleted -- forks must read through soft-deleted sources.
+  */
+  private readForkedMessages;
   read(streamPath: string, offset?: string): {
     messages: Array<StreamMessage>;
     upToDate: boolean;
@@ -533,8 +625,7 @@ declare class FileBackedStreamStore {
   private notifyLongPollsClosed;
   private cancelLongPollsForStream;
   private removePendingLongPoll;
-}
-//#endregion
+} //#endregion
 //#region src/server.d.ts
 /**
 * HTTP server for testing durable streams.

package/dist/index.d.ts

@@ -57,6 +57,12 @@ interface Stream {
   */
   createdAt: number;
   /**
+  * Timestamp of the last read or write (for TTL renewal).
+  * Initialized to createdAt. Updated on GET reads and POST appends.
+  * HEAD requests do NOT update this field.
+  */
+  lastAccessedAt: number;
+  /**
   * Producer states for idempotent writes.
   * Maps producer ID to their epoch and sequence state.
   */
@@ -75,6 +81,24 @@ interface Stream {
     epoch: number;
     seq: number;
   };
+  /**
+  * Source stream path (set when this stream is a fork).
+  */
+  forkedFrom?: string;
+  /**
+  * Divergence offset from the source stream.
+  * Format: "0000000000000000_0000000000000000"
+  */
+  forkOffset?: string;
+  /**
+  * Number of forks referencing this stream.
+  * Defaults to 0.
+  */
+  refCount: number;
+  /**
+  * Whether this stream is logically deleted but retained for fork readers.
+  */
+  softDeleted?: boolean;
 }
 /**
 * Event data for stream lifecycle hooks.
@@ -251,13 +275,19 @@ declare class StreamStore {
   */
   private isExpired;
   /**
-  * Get a stream, deleting it if expired.
-  * Returns undefined if stream doesn't exist or is expired.
+  * Get a stream, handling expiry.
+  * Returns undefined if stream doesn't exist or is expired (and has no refs).
+  * Expired streams with refCount > 0 are soft-deleted instead of fully deleted.
   */
   private getIfNotExpired;
   /**
+  * Update lastAccessedAt to now. Called on reads and appends (not HEAD).
+  */
+  touchAccess(path: string): void;
+  /**
   * Create a new stream.
   * @throws Error if stream already exists with different config
+  * @throws Error if fork source not found, soft-deleted, or offset invalid
   * @returns existing stream if config matches (idempotent)
   */
   create(path: string, options?: {
@@ -266,21 +296,36 @@ declare class StreamStore {
     expiresAt?: string;
     initialData?: Uint8Array;
     closed?: boolean;
+    forkedFrom?: string;
+    forkOffset?: string;
   }): Stream;
   /**
+  * Resolve fork expiry per the decision table.
+  * Forks have independent lifetimes — no capping at source expiry.
+  */
+  private resolveForkExpiry;
+  /**
   * Get a stream by path.
   * Returns undefined if stream doesn't exist or is expired.
+  * Returns soft-deleted streams (caller should check stream.softDeleted).
   */
   get(path: string): Stream | undefined;
   /**
-  * Check if a stream exists (and is not expired).
+  * Check if a stream exists, is not expired, and is not soft-deleted.
   */
   has(path: string): boolean;
   /**
   * Delete a stream.
+  * If the stream has forks (refCount > 0), it is soft-deleted instead of fully removed.
+  * Returns true if the stream was found and deleted (or soft-deleted).
   */
   delete(path: string): boolean;
   /**
+  * Fully delete a stream and cascade to soft-deleted parents
+  * whose refcount drops to zero.
+  */
+  private deleteWithCascade;
+  /**
   * Validate producer state WITHOUT mutating.
   * Returns proposed state to commit after successful append.
   * Implements Kafka-style idempotent producer validation.
@@ -346,6 +391,7 @@ declare class StreamStore {
   getProducerEpoch(path: string, producerId: string): number | undefined;
   /**
   * Read messages from a stream starting at the given offset.
+  * For forked streams, stitches messages from the source chain and the fork's own messages.
   * @throws Error if stream doesn't exist or is expired
   */
   read(path: string, offset?: string): {
@@ -353,6 +399,20 @@ declare class StreamStore {
     upToDate: boolean;
   };
   /**
+  * Read from a forked stream, stitching inherited and own messages.
+  */
+  private readFromFork;
+  /**
+  * Read a stream's own messages starting after the given offset.
+  */
+  private readOwnMessages;
+  /**
+  * Recursively read messages from a fork's source chain.
+  * Reads from source (and its sources if also forked), capped at forkOffset.
+  * Does NOT check softDeleted — forks must read through soft-deleted sources.
+  */
+  private readForkedMessages;
+  /**
   * Format messages for response.
   * For JSON mode, wraps concatenated data in array brackets.
   * @throws Error if stream doesn't exist or is expired
@@ -450,15 +510,25 @@ declare class FileBackedStreamStore {
   */
   getProducerEpoch(streamPath: string, producerId: string): number | undefined;
   /**
+  * Update lastAccessedAt to now. Called on reads and appends (not HEAD).
+  */
+  touchAccess(streamPath: string): void;
+  /**
   * Check if a stream is expired based on TTL or Expires-At.
   */
   private isExpired;
   /**
   * Get stream metadata, deleting it if expired.
-  * Returns undefined if stream doesn't exist or is expired.
+  * Returns undefined if stream doesn't exist or is expired (and has no refs).
+  * Expired streams with refCount > 0 are soft-deleted instead of fully deleted.
   */
   private getMetaIfNotExpired;
   /**
+  * Resolve fork expiry per the decision table.
+  * Forks have independent lifetimes — no capping at source expiry.
+  */
+  private resolveForkExpiry;
+  /**
   * Close the store, closing all file handles and database.
   * All data is already fsynced on each append, so no final flush needed.
   */
@@ -469,10 +539,17 @@ declare class FileBackedStreamStore {
     expiresAt?: string;
     initialData?: Uint8Array;
     closed?: boolean;
+    forkedFrom?: string;
+    forkOffset?: string;
   }): Promise<Stream>;
   get(streamPath: string): Stream | undefined;
   has(streamPath: string): boolean;
   delete(streamPath: string): boolean;
+  /**
+  * Fully delete a stream and cascade to soft-deleted parents
+  * whose refcount drops to zero.
+  */
+  private deleteWithCascade;
   append(streamPath: string, data: Uint8Array, options?: AppendOptions & {
     isInitialCreate?: boolean;
   }): Promise<StreamMessage | AppendResult | null>;
@@ -503,6 +580,21 @@ declare class FileBackedStreamStore {
     alreadyClosed: boolean;
     producerResult?: ProducerValidationResult;
   } | null>;
+  /**
+  * Read messages from a specific segment file.
+  * @param segmentPath - Path to the segment file
+  * @param startByte - Start byte offset (skip messages at or before this offset)
+  * @param baseByteOffset - Base byte offset to add to physical offsets (for fork stitching)
+  * @param capByte - Optional cap: stop reading when logical offset exceeds this value
+  * @returns Array of messages with properly computed offsets
+  */
+  private readMessagesFromSegmentFile;
+  /**
+  * Recursively read messages from a fork's source chain.
+  * Reads from source (and its sources if also forked), capped at capByte.
+  * Does NOT check softDeleted -- forks must read through soft-deleted sources.
+  */
+  private readForkedMessages;
   read(streamPath: string, offset?: string): {
     messages: Array<StreamMessage>;
     upToDate: boolean;
@@ -533,8 +625,7 @@ declare class FileBackedStreamStore {
   private notifyLongPollsClosed;
   private cancelLongPollsForStream;
   private removePendingLongPoll;
-}
-//#endregion
+} //#endregion
 //#region src/server.d.ts
 /**
 * HTTP server for testing durable streams.