Class: TypedCache::Namespace

Inherits:
Object
  • Object
show all
Defined in:
lib/typed_cache/namespace.rb

Overview

Provides a type-safe, composable namespace abstraction for cache keys.

The Namespace class allows you to create hierarchical namespaces for cache keys, ensuring that keys are properly scoped and collisions are avoided. Each Namespace instance can generate cache keys (via #key), create nested namespaces (via #nested), and traverse to parent namespaces (via #parent_namespace).

Example:

ns = TypedCache::Namespace.at("users")
ns.key("123") # => #<TypedCache::CacheKey namespace=users key=123>
ns2 = ns.nested("sessions")
ns2.key("abc") # => #<TypedCache::CacheKey namespace=users:sessions key=abc>

Namespaces are composable and immutable. The key factory can be customized for advanced use cases.

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(namespace, &key_factory) {|key| ... } ⇒ Namespace

Initializes a new Namespace instance with the given namespace string and key factory.

Example:

Namespace.new("users") { |key| CacheKey.new("users", key) }

Yields:

  • (key) —

    the key string to create a CacheKey from

Yield Returns:



62
63
64
65
 
# File 'lib/typed_cache/namespace.rb', line 62

def initialize(namespace, &key_factory)
  @namespace = namespace
  @key_factory = key_factory
end

Class Method Details

.at(namespace, *namespaces) ⇒ Namespace

Returns a new Namespace instance rooted at the given namespace string.

Example:

TypedCache::Namespace.at("users", "sessions") # => #<TypedCache::Namespace namespace=users:sessions>

The returned Namespace can be further nested or used to generate cache keys.



32
33
34
 
# File 'lib/typed_cache/namespace.rb', line 32

def at(namespace, *namespaces)
  root.join(namespace, *namespaces)
end

.root ⇒ Namespace

Returns the root Namespace instance (with an empty namespace).

Example:

TypedCache::Namespace.root # => #<TypedCache::Namespace namespace=>

The root namespace is useful as a starting point for building nested namespaces.



46
47
48
 
# File 'lib/typed_cache/namespace.rb', line 46

def root
  new(TypedCache.config.default_namespace) { |ns, key| CacheKey.new(ns, key) }
end

Instance Method Details

#==(other) ⇒ Object 



176
177
178
 
# File 'lib/typed_cache/namespace.rb', line 176

def ==(other)
  other.is_a?(self.class) && other.to_s == to_s
end

#hash ⇒ Object 



171
172
173
 
# File 'lib/typed_cache/namespace.rb', line 171

def hash
  [@namespace].hash
end

#inspect ⇒ String

Returns a string representation of the Namespace instance for debugging.

Example:

ns = Namespace.at("users")
ns.inspect # => "#<TypedCache::Namespace namespace=users>"



166
167
168
 
# File 'lib/typed_cache/namespace.rb', line 166

def inspect
  "Namespace(#{@namespace})"
end

#join(*namespaces, &key_factory) ⇒ Namespace

Creates a new namespace by joining the current namespace with the given namespaces.

Example:

ns = Namespace.at("users")
ns.join("sessions", "admin") # => #<TypedCache::Namespace namespace=users:sessions:admin>

If no key_factory is provided, the parent's key factory is inherited.



99
100
101
102
103
 
# File 'lib/typed_cache/namespace.rb', line 99

def join(*namespaces, &key_factory)
  key_factory ||= @key_factory

  self.class.new([@namespace, *namespaces].join(delimiter), &key_factory)
end

#key(key) ⇒ CacheKey

Creates a cache key using the namespace's key factory.

Example:

ns = Namespace.at("users")
ns.key("123") # => #<TypedCache::CacheKey namespace=users key=123>



137
138
139
 
# File 'lib/typed_cache/namespace.rb', line 137

def key(key)
  @key_factory.call(self, key)
end

#nested(namespace, &key_factory) ⇒ Namespace

Creates a nested namespace by appending the given namespace to the current one.

Example:

ns = Namespace.at("users")
ns.nested("sessions") # => #<TypedCache::Namespace namespace=users:sessions>

If no key_factory is provided, the parent's key factory is inherited.



80
81
82
83
84
 
# File 'lib/typed_cache/namespace.rb', line 80

def nested(namespace, &key_factory)
  key_factory ||= @key_factory

  self.class.new([@namespace, namespace].join(delimiter), &key_factory)
end

#parent_namespace ⇒ Namespace

Returns the parent namespace by removing the last namespace segment.

Example:

ns = Namespace.at("users:sessions")
ns.parent_namespace # => #<TypedCache::Namespace namespace=users>

For root namespaces (empty string), returns self.



116
117
118
119
120
121
122
123
124
125
 
# File 'lib/typed_cache/namespace.rb', line 116

def parent_namespace
  return self if @namespace.empty?

  case pathsep_idx = @namespace.rindex(delimiter)
  when nil
    self.class.root
  else
    self.class.new(@namespace[...pathsep_idx])
  end
end

#root? ⇒ Boolean 



142
 
# File 'lib/typed_cache/namespace.rb', line 142

def root? = @namespace.empty?

#to_s ⇒ String

Returns the namespace string representation.

Example:

ns = Namespace.at("users:sessions")
ns.to_s # => "users:sessions"



153
154
155
 
# File 'lib/typed_cache/namespace.rb', line 153

def to_s
  @namespace
end