Module: Ace::B36ts

Defined in:
lib/ace/b36ts.rb,
lib/ace/b36ts/cli.rb,
lib/ace/b36ts/version.rb,
lib/ace/b36ts/atoms/formats.rb,
lib/ace/b36ts/atoms/format_specs.rb,
lib/ace/b36ts/atoms/format_codecs.rb,
lib/ace/b36ts/cli/commands/config.rb,
lib/ace/b36ts/cli/commands/decode.rb,
lib/ace/b36ts/cli/commands/encode.rb,
lib/ace/b36ts/commands/config_command.rb,
lib/ace/b36ts/commands/decode_command.rb,
lib/ace/b36ts/commands/encode_command.rb,
lib/ace/b36ts/atoms/compact_id_encoder.rb,
lib/ace/b36ts/molecules/config_resolver.rb

Overview

B36ts module providing Base36 compact ID generation for timestamps.

This module provides a 6-character Base36 encoding for timestamps that replaces traditional 14-character timestamp formats (YYYYMMDD-HHMMSS).

Examples:

Quick encoding

Ace::B36ts.encode(Time.now)
# => "i50jj3"

Quick decoding

Ace::B36ts.decode("i50jj3")
# => 2025-01-06 12:30:00 UTC

Format detection

Ace::B36ts.detect_format("i50jj3")      # => :"2sec"
Ace::B36ts.detect_format("20250106-123000") # => :timestamp

Defined Under Namespace

Modules: Atoms, CLI, Commands, Molecules Classes: Error

Constant Summary collapse

VERSION =

Version 0.2.0: Gem renamed from ace-timestamp to ace-support-timestamp Namespace changed from Ace::Timestamp to Ace::Support::Timestamp Version 0.6.0: Gem renamed from ace-support-timestamp to ace-b36ts Namespace changed from Ace::Support::Timestamp to Ace::B36ts

'0.14.8'

Class Method Summary collapse

Class Method Details

.config ⇒ Hash

Load configuration using ace-config cascade

Returns:

  • (Hash) —

    Configuration hash



194
195
196
 
# File 'lib/ace/b36ts.rb', line 194

def self.config
  Molecules::ConfigResolver.resolve
end

.debug? ⇒ Boolean

Check if debug mode is enabled

Returns:

  • (Boolean) —

    True if debug mode is enabled



47
48
49
 
# File 'lib/ace/b36ts.rb', line 47

def self.debug?
  ENV["ACE_DEBUG"] == "1" || ENV["DEBUG"] == "1"
end

.decode(compact_id, format: nil, year_zero: nil) ⇒ Time

Decode a compact ID to a Time object (convenience method)

Parameters:

  • compact_id (String) —

    The compact ID to decode

  • format (Symbol, nil) (defaults to: nil) —

    Format of the ID (default: :“2sec” for 6-char, or auto-detect)

  • year_zero (Integer, nil) (defaults to: nil) —

    Optional year_zero override

Returns:

  • (Time) —

    Decoded time in UTC



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/ace/b36ts.rb', line 77

def self.decode(compact_id, format: nil, year_zero: nil)
  config = Molecules::ConfigResolver.resolve(year_zero: year_zero)

  if format
    Atoms::CompactIdEncoder.decode_with_format(
      compact_id,
      format: format,
      year_zero: config[:year_zero],
      alphabet: config[:alphabet]
    )
  else
    # Default to 2sec format for backward compatibility with 6-char IDs
    Atoms::CompactIdEncoder.decode(
      compact_id,
      year_zero: config[:year_zero],
      alphabet: config[:alphabet]
    )
  end
end

.decode_auto(compact_id, year_zero: nil) ⇒ Time

Decode a compact ID with automatic format detection (convenience method)

Automatically detects the format based on ID length and value ranges:

  • 2 chars: month format

  • 3 chars: day or week format (auto-detected by 3rd char value)

  • 4 chars: 40min format

  • 6 chars: 2sec format

  • 7 chars: 50ms format

  • 8 chars: ms format

Parameters:

  • compact_id (String) —

    The compact ID to decode (2-8 characters)

  • year_zero (Integer, nil) (defaults to: nil) —

    Optional year_zero override

Returns:

  • (Time) —

    Decoded time in UTC

Raises:

  • (ArgumentError) —

    If format cannot be detected



111
112
113
114
115
116
117
118
 
# File 'lib/ace/b36ts.rb', line 111

def self.decode_auto(compact_id, year_zero: nil)
  config = Molecules::ConfigResolver.resolve(year_zero: year_zero)
  Atoms::CompactIdEncoder.decode_auto(
    compact_id,
    year_zero: config[:year_zero],
    alphabet: config[:alphabet]
  )
end

.decode_path(path_string, year_zero: nil) ⇒ Time

Decode a hierarchical split path into a Time object

Parameters:

  • path_string (String) —

    Split path string

  • year_zero (Integer, nil) (defaults to: nil) —

    Optional year_zero override

Returns:

  • (Time) —

    Decoded time in UTC



144
145
146
147
148
149
150
151
 
# File 'lib/ace/b36ts.rb', line 144

def self.decode_path(path_string, year_zero: nil)
  config = Molecules::ConfigResolver.resolve(year_zero: year_zero)
  Atoms::CompactIdEncoder.decode_path(
    path_string,
    year_zero: config[:year_zero],
    alphabet: config[:alphabet]
  )
end

.detect_format(value) ⇒ Symbol?

Detect the format of a timestamp string

Parameters:

  • value (String) —

    The timestamp string

Returns:

  • (Symbol, nil) —

    :“2sec”, :timestamp, or nil



180
181
182
 
# File 'lib/ace/b36ts.rb', line 180

def self.detect_format(value)
  Atoms::Formats.detect(value)
end

.encode(time, format: nil, year_zero: nil) ⇒ String

Encode a Time object to a compact ID (convenience method)

Parameters:

  • time (Time) —

    The time to encode

  • format (Symbol, nil) (defaults to: nil) —

    Output format (default: :“2sec”) Supported formats: :month (2 chars), :week (3 chars), :day (3 chars), :“40min” (4 chars), :“2sec” (6 chars), :“50ms” (7 chars), :ms (8 chars)

  • year_zero (Integer, nil) (defaults to: nil) —

    Optional year_zero override

Returns:

  • (String) —

    Compact ID (length varies by format)



59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/ace/b36ts.rb', line 59

def self.encode(time, format: nil, year_zero: nil)
  config = Molecules::ConfigResolver.resolve(year_zero: year_zero)
  effective_format = format || config[:default_format]&.to_sym || :"2sec"

  Atoms::CompactIdEncoder.encode_with_format(
    time,
    format: effective_format,
    year_zero: config[:year_zero],
    alphabet: config[:alphabet]
  )
end

.encode_split(time, levels:, path_only: false, year_zero: nil) ⇒ Hash, String

Encode a Time object into split components for hierarchical paths

Parameters:

  • time (Time) —

    The time to encode

  • levels (Array<Symbol>, String) —

    Split levels (month, week, day, block)

  • path_only (Boolean) (defaults to: false) —

    Return only the path string

  • year_zero (Integer, nil) (defaults to: nil) —

    Optional year_zero override

Returns:

  • (Hash, String) —

    Split component hash or path string



127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/ace/b36ts.rb', line 127

def self.encode_split(time, levels:, path_only: false, year_zero: nil)
  config = Molecules::ConfigResolver.resolve(year_zero: year_zero)
  result = Atoms::CompactIdEncoder.encode_split(
    time,
    levels: levels,
    year_zero: config[:year_zero],
    alphabet: config[:alphabet]
  )

  path_only ? result[:path] : result
end

.now(year_zero: nil) ⇒ String

Generate a compact ID for the current time (convenience method)

Parameters:

  • year_zero (Integer, nil) (defaults to: nil) —

    Optional year_zero override

Returns:

  • (String) —

    6-character compact ID for current time



188
189
190
 
# File 'lib/ace/b36ts.rb', line 188

def self.now(year_zero: nil)
  encode(Time.now.utc, year_zero: year_zero)
end

.reset_config! ⇒ Object

Reset configuration cache (useful for testing)



199
200
201
 
# File 'lib/ace/b36ts.rb', line 199

def self.reset_config!
  Molecules::ConfigResolver.reset!
end

.valid?(compact_id) ⇒ Boolean

Validate if a string is a valid 6-character compact ID (legacy method)

NOTE: This method only validates 6-character “2sec” format IDs. For validating IDs of any format, use valid_any_format? instead.

Parameters:

  • compact_id (String) —

    The string to validate

Returns:

  • (Boolean) —

    True if valid 6-char compact ID format

See Also:



161
162
163
 
# File 'lib/ace/b36ts.rb', line 161

def self.valid?(compact_id)
  Atoms::CompactIdEncoder.valid?(compact_id)
end

.valid_any_format?(compact_id) ⇒ Boolean

Validate if a string is a valid compact ID of any format

Supports all 7 formats: month (2 chars), week (3 chars), day (3 chars), 40min (4 chars), 2sec (6 chars), 50ms (7 chars), ms (8 chars).

Parameters:

  • compact_id (String) —

    The string to validate (2-8 characters)

Returns:

  • (Boolean) —

    True if valid compact ID of any format



172
173
174
 
# File 'lib/ace/b36ts.rb', line 172

def self.valid_any_format?(compact_id)
  Atoms::CompactIdEncoder.valid_any_format?(compact_id)
end