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) }

Parameters:

  • namespace (String) —

    the namespace string for this instance

  • key_factory (Proc) —

    a block that creates CacheKey instances from key strings

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.

Parameters:

  • namespace (String) —

    the root namespace

  • namespaces (Array<String>) —

    additional namespaces to join

Returns:

  • (Namespace) —

    a new Namespace instance at the given root



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.

Returns:



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>"

Returns:

  • (String) —

    a debug-friendly string representation



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.

Parameters:

  • namespaces (Array<String>) —

    the namespaces to join

  • key_factory (Proc, nil) —

    optional custom key factory for the joined namespace

Returns:

  • (Namespace) —

    a new Namespace instance with the combined namespace



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>

Parameters:

  • key (String) —

    the key string to create a cache key from

Returns:



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.

Parameters:

  • namespace (String) —

    the namespace to append

  • key_factory (Proc, nil) —

    optional custom key factory for the nested namespace

Returns:

  • (Namespace) —

    a new Namespace instance with the combined namespace



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.

Returns:

  • (Namespace) —

    the parent namespace, or self if already at root



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

Returns:

  • (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"

Returns:

  • (String) —

    the namespace string



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

def to_s
  @namespace
end