module Sepia::Serializable

Overview

Module for objects that serialize to a single file.

The Serializable module provides a contract for objects that can be serialized to and deserialized from a single string representation.

⚠️ WARNING: The Serializable API and on-disk format are subject to change. Data migrations will be required when upgrading Sepia versions. Classes including this module must implement two methods:

File Storage

Serializable objects are stored as individual files in the filesystem. The file contains the exact string returned by to_sepia.

Example

class SimpleNote < Sepia::Object
  include Sepia::Serializable

  property text : String

  def initialize(@text = "")
  end

  # Serialize to a simple string
  def to_sepia : String
    @text
  end

  # Deserialize from a string
  def self.from_sepia(sepia_string : String) : self
    new(sepia_string)
  end
end

note = SimpleNote.new("Hello, World!")
note.save # Creates a file containing "Hello, World!"

loaded = SimpleNote.load(note.sepia_id)
loaded.text # => "Hello, World!"

JSON Serialization

For more complex objects, you can serialize to JSON:

class User < Sepia::Object
  include Sepia::Serializable

  property name : String
  property email : String

  def initialize(@name = "", @email = "")
  end

  def to_sepia : String
    {name: @name, email: @email}.to_json
  end

  def self.from_sepia(json : String) : self
    data = JSON.parse(json)
    new(data["name"].as_s, data["email"].as_s)
  end
end

Defined in:

sepia/serializable.cr

Instance Method Summary

Instance Method Detail

def log_activity(action : String, metadata) #

Logs an activity event for this object.

This method allows objects to log arbitrary activities that are not related to object persistence (save/delete operations). Activities are stored in the object's event log alongside other events.

Parameters

  • action : Description of the activity (e.g., "moved_lane", "edited")
  • metadata : Optional metadata for the activity (values will be converted to strings)

Example

note.log_activity("moved_lane", {"from" => "In Progress", "to" => "Done", "user" => "alice"})

# Simple version
note.log_activity("edited")

[View source]
def log_activity(action : String) #

Logs an activity event for this object (without metadata).

This method allows objects to log arbitrary activities that are not related to object persistence (save/delete operations). Activities are stored in the object's event log alongside other events.

Parameters

  • action : Description of the activity (e.g., "moved_lane", "edited")

Example

note.log_activity("edited")

[View source]
def sepia_references : Enumerable(Sepia::Object) #

Returns all Sepia objects referenced by this object.

This method is used by the garbage collector to track object relationships. By default, Serializable objects don't reference other Sepia objects.

Override this method if your Serializable contains references to other Sepia objects that should be tracked.

Returns

An Enumerable of Sepia::Object instances referenced by this object.

Example

class Document < Sepia::Object
  include Sepia::Serializable

  property author : User

  def sepia_references : Enumerable(Sepia::Object)
    [@author] if @author
  end
end

[View source]