asset_db 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d71f04f4789fbd8bf52decfa901cfc6c68df8e04e8d708bba64e7d5fd95f0fbc
-  data.tar.gz: 57c9bf86e113b875eb3829f11c89db95f55c35262b2efa09a99cdf276e2b1301
+  metadata.gz: 42dde564b2ddc791818bc1431399d8f51a193f8e4470d157b74cb200999de40c
+  data.tar.gz: ce91c3dbeb2690f282f2627be18cd1c2cf9aec72012a68a0b8e97c713103d3a7
 SHA512:
-  metadata.gz: 456ce8e2f6f7db0c3c83b30ab6b3130bf10edd30d3621638c58eb133bb4cc0ba8488b103463d08f285873371d365ba8240cde48104d5fee152819b25f80dda64
-  data.tar.gz: 4496834d507fc071851ce7ae6110f5d926c7f8f17d543a969661c96c2e58706d43f3f7594eee93684c87e4c5065719346b13ada0d46ac5abcc5c81a20a529a59
+  metadata.gz: e484a766a3ab1c2845c1a1dc04e05bfc2395ca854f16945037c69597cf1a48c97b2dd7a79004a1621d4e93723ee9617d59366b71f8a0aaf0cfab1e8cc3bb10a6
+  data.tar.gz: 9f270d3af193419c86e44dbd78cbd3125ad95742c6b264be277c0e319a2c2175f902498484860c8a3964c9318c8ce9d5e485103a094cc762f2c47354cec56692

data/lib/asset_db/asset.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module AssetDB
+	class Asset
+		attr_reader :type, :id, :url, :metadata, :group, :package
+
+		def initialize(type:, group:, package:, url:, metadata: nil, id: url)
+			@type     = type.to_sym
+			@url      = url.to_s.freeze
+			@metadata = metadata
+			@id       = id.to_s.freeze
+			@package  = package
+			@group    = group
+		end
+
+		def ==(other)
+			other.is_a?(Asset) && other.id == id
+		end
+		alias eql? ==
+
+		def hash
+			id.hash
+		end
+
+		def protocol_url?
+			@protocol ||= url =~ /\A[A-Za-z][A-Za-z0-9+\-.]*:\/\//
+		end
+	end
+end

data/lib/asset_db/database.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module AssetDB
+	class Database
+		CONFIG_RESERVED = %w[types basepath folders].freeze
+
+		attr_reader :asset_types, :basepath, :groups, :resolver
+		attr_accessor :separator
+
+		def initialize(asset_types: nil, basepath: nil)
+			@asset_types = (asset_types&.map(&:to_sym) || %i[css js]).freeze
+			@basepath   = (basepath || '').dup
+			@separator   = nil
+			@groups      = {} # {id ⇒ Group}
+			@resolver    = Resolver.new(self)
+		end
+
+		# DSL helpers
+		G_FOLDER_DEFAULT = Group::FOLDER_DEFAULT
+		def group(id, folder: G_FOLDER_DEFAULT, &block)
+			g = (@groups[id.to_s] ||= Group.new(self, id, folder: folder))
+			yield g if block
+			g
+		end
+
+		def groups
+			@groups.values
+		end
+		def asset_types
+			@asset_types
+		end
+
+		# Strict fetch for resolver
+		def group!(id)
+			@groups[id.to_s] or raise Errors::UnknownGroupError, id
+		end
+
+		def package!(g_id, p_id)
+			group!(g_id).instance_variable_get(:@packages_hash)[p_id.to_s] or
+				raise Errors::UnknownPackageError, "#{g_id}/#{p_id}"
+		end
+
+		# ---------------  URL expansion ---------------
+		def build_url(asset)
+			return asset.url if asset.protocol_url?
+			return ensure_root_slash(asset.url) if asset.url.start_with?('/')
+
+			group  = asset.group
+			package = asset.package
+			path = @basepath.dup
+			unless path.empty?
+				path.gsub!(':type',    asset.type.to_s)
+				path.gsub!(':group',   group.folder_segment.to_s)
+				path.gsub!(':package', package.folder_segment.to_s)
+			end
+
+			ensure_root_slash(File.join(path, asset.url))
+		end
+
+		def ensure_root_slash(pth)
+			('/' + pth.gsub(%r{^/+}, '')).gsub(%r{/{2,}}, '/')
+		end
+
+		# ---------------  Config loader ---------------
+		def self.from_config(cfg)
+			cfg = cfg.transform_keys(&:to_s)
+			db  = new(asset_types: cfg['types'], basepath: cfg['basepath'])
+
+			folders_map = (cfg['folders'] || {}).transform_keys(&:to_s).dup
+			if sep = folders_map.delete('separator')
+				db.separator = sep.to_s
+			end
+
+			cfg.each do |g_id, g_spec|
+				next if CONFIG_RESERVED.include?(g_id)
+			
+				raise Errors::InvalidIdentifierError,
+							"group name ‘#{g_id}’ conflicts with asset type" \
+							if db.asset_types.include?(g_id.to_sym)
+			
+				# ----------  GROUP ---------- #
+				if (folders_map.key? g_id)
+					g = db.group(g_id, folder: folders_map[g_id])           # explicit override (can be nil/false/empty)
+				else
+					g = db.group(g_id)                                      # default ⇒ id
+				end
+				gid = g_id.to_s
+			
+				# ----------  PACKAGES ---------- #
+				g_spec.each do |p_id, p_spec|
+					p_key = "#{gid}#{db.separator}#{p_id}"                                # composite key for folder overrides
+			
+					if (folders_map.key? p_key)
+						pkg = g.package(p_id, folder: folders_map[p_key])   # explicit override
+					else
+						pkg = g.package(p_id)                               # default ⇒ id
+					end
+			
+					p_spec.each do |k, v|
+						key = k.to_s
+						if db.asset_types.include?(key.to_sym)              # ASSETS
+							Array(v).each { |url| pkg.asset(key, url == true ? p_id + '.' + key : url) }
+						else                                                # DEPENDENCIES
+							Array(v).each { |target_pkg| pkg.depends_on(target_pkg, group_id: key) }
+						end
+					end
+				end
+			end
+			
+			db
+		end
+
+		# Unify any number (≥2) of Package or PackageCollection into one collection
+		def unify(*items)
+			# Simple returns
+			if items.empty?
+				return nil
+			elsif items.size == 1
+				return Resolver::PackageCollection.new(self, items.first)
+			end
+
+			# Combine packages
+			merged = items.flat_map do |i|
+			case i
+				when Resolver::PackageCollection
+					i.instance_variable_get(:@packages)
+				when Package
+					[i]
+				else
+					raise ArgumentError, "Cannot unify #{i.inspect}"
+				end
+			end
+			Resolver::PackageCollection.new(self, merged)
+		end
+
+		def validate_identifier!(name)
+			if separator && name.to_s.include?(separator)
+				raise Errors::InvalidIdentifierError, "'#{separator}' forbidden in identifier #{name.inspect}"
+			end
+		end
+
+	end
+end

data/lib/asset_db/errors.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module AssetDB
+	module Errors
+		class AssetDBError          < StandardError; end
+		class UnknownGroupError     < AssetDBError; end
+		class UnknownPackageError   < AssetDBError; end
+		class CycleError            < AssetDBError
+			attr_reader :cycle
+			def initialize(cycle)
+				@cycle = cycle
+				super("Dependency cycle detected: " +
+				      cycle.map { |p| "#{p.group.id}:#{p.id}" }.join(' → '))
+			end
+		end
+		class InvalidIdentifierError < AssetDBError; end
+	end
+end

data/lib/asset_db/group.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module AssetDB
+	class Group
+		FOLDER_DEFAULT = :__default
+
+		attr_reader :database, :id
+
+		def initialize(database, id, folder: FOLDER_DEFAULT)
+			database.validate_identifier!(id)
+			@database      = database
+			@id            = id.to_s
+			@folder        = folder.equal?(FOLDER_DEFAULT) ? FOLDER_DEFAULT : folder
+			@packages_hash = {} # {id ⇒ Package}
+		end
+
+		# DSL – fetch or create.
+		def package(id, folder: FOLDER_DEFAULT, &block)
+			pkg = (@packages_hash[id.to_s] ||= Package.new(self, id, folder: folder))
+			yield pkg if block
+			pkg
+		end
+
+		def packages
+			@packages_hash.values
+		end
+		def package_ids
+			@packages_hash.keys
+		end
+		def folder_spec
+			@folder
+		end
+
+		def folder_segment
+			return id            if @folder.equal?(FOLDER_DEFAULT)
+			return nil           if !@folder || @folder == '' || @folder == false
+			@folder.to_s
+		end
+
+	end
+end

data/lib/asset_db/package.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module AssetDB
+	class Package
+		FOLDER_DEFAULT = :__default
+
+		attr_reader :id, :group
+
+		def initialize(group, id, folder: FOLDER_DEFAULT)
+			@group        = group
+			database.validate_identifier!(id)
+			@id           = id.to_s
+			@folder       = folder.equal?(FOLDER_DEFAULT) ? FOLDER_DEFAULT : folder
+			@assets       = Hash.new { |h, k| h[k] = [] }  # {type ⇒ [Asset]}
+			@dependencies = []                             # [[group_id, package_id]]
+			@cache        = {}                             # {type|:all ⇒ …}
+		end
+
+		def asset(type, url, metadata = nil, id: url)
+			type = type.to_sym
+			check_type!(type)
+			@assets[type] << Asset.new(type: type, url: url, group: group, package: self, metadata: metadata, id: id)
+			invalidate_cache
+			self
+		end
+
+		def depends_on(pkg_id, group_id: group.id)
+			@dependencies << [group_id.to_s, pkg_id.to_s]
+			invalidate_cache
+			self
+		end
+
+		def resolved_assets(type = nil)
+			key = type ? type.to_sym : :all
+			@cache[key] ||= database.resolver.resolve(self, type: type&.to_sym)
+		end
+
+		def +(other)
+			database.unify(self, other)
+		end
+
+		def folder_segment
+			return id            if @folder.equal?(FOLDER_DEFAULT)
+			return nil           if !@folder || @folder == '' || @folder == false
+			@folder.to_s
+		end
+
+		def assets
+			@assets
+		end
+		def dependencies
+			@dependencies
+		end
+		def key?
+			"#{group.id}/#{id}".freeze
+		end
+		def database
+			group.database
+		end
+
+		private
+
+		def invalidate_cache
+			@cache.clear
+		end
+		def check_type!(t)
+			database.asset_types.include?(t) or raise ArgumentError, "Unknown type #{t}"
+		end
+
+	end
+end

data/lib/asset_db/resolver.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module AssetDB
+	class Resolver
+		def initialize(database)
+			@database = database
+			@memo     = {} # {pkg_key ⇒ {type|:all ⇒ result}}
+			@mutex    = Mutex.new
+		end
+
+		def resolve(pkg, type: nil)
+			type_key = type ? type.to_sym : :all
+			@mutex.synchronize { (@memo[pkg.key?] ||= {})[type_key] ||= (type ? dfs_type(pkg, type_key) : dfs_all(pkg)) }
+		end
+
+		# --------------------------------------------------
+		#   private helpers
+		# --------------------------------------------------
+		private
+
+		def dfs_type(pkg, type, visiting = Set.new, stack = [])
+			return @memo.dig(pkg.key?, type) if @memo.dig(pkg.key?, type)
+
+			raise Errors::CycleError.new(stack + [pkg]) if visiting.include?(pkg.key?)
+			visiting.add(pkg.key?); stack.push(pkg)
+
+			ordered     = []
+			seen_ids    = Set.new
+
+			pkg.dependencies.each do |(g_id, p_id)|
+				dep_pkg = @database.package!(g_id, p_id)
+				dfs_type(dep_pkg, type, visiting, stack).each do |asset|
+					next if seen_ids.include?(asset.id)
+					seen_ids << asset.id
+					ordered   << asset
+				end
+			end
+
+			pkg.assets[type].each do |asset|
+				next if seen_ids.include?(asset.id)
+				seen_ids << asset.id
+				ordered   << asset
+			end
+
+			stack.pop; visiting.delete(pkg.key?)
+			ordered.freeze
+		end
+
+		def dfs_all(pkg, visiting = Set.new, stack = [])
+			return @memo.dig(pkg.key?, :all) if @memo.dig(pkg.key?, :all)
+
+			raise Errors::CycleError.new(stack + [pkg]) if visiting.include?(pkg.key?)
+			visiting.add(pkg.key?); stack.push(pkg)
+
+			result     = Hash.new { |h, k| h[k] = [] }
+			seen       = Hash.new { |h, k| h[k] = Set.new }
+
+			pkg.dependencies.each do |(g_id, p_id)|
+				dep_pkg = @database.package!(g_id, p_id)
+				dfs_all(dep_pkg, visiting, stack).each do |t, assets|
+					assets.each do |asset|
+						next if seen[t].include?(asset.id)
+						seen[t]   << asset.id
+						result[t] << asset
+					end
+				end
+			end
+
+			pkg.assets.each do |t, assets|
+				assets.each do |asset|
+					next if seen[t].include?(asset.id)
+					seen[t]   << asset.id
+					result[t] << asset
+				end
+			end
+
+			stack.pop; visiting.delete(pkg.key?)
+			result.transform_values!(&:freeze).freeze
+		end
+
+		# --------------------------------------------------
+		#   lightweight immutable union façade
+		# --------------------------------------------------
+		class PackageCollection
+			include Enumerable
+
+			def initialize(database, pkgs)
+				@database = database
+				@packages = Array(pkgs).uniq
+				@cache    = {} # {[type, key] ⇒ [Asset]}
+			end
+
+			def +(other)
+				@database.unify(self, other)
+			end
+
+			def each_asset(type = nil, &block)
+				return @database.asset_types.each { |t| each_asset(t, &block) } if type.nil?
+
+				type = type.to_sym
+				key  = [type, @packages.map(&:key?).sort].hash
+				@cache[key] ||= begin
+					seen = Set.new
+					arr  = []
+					@packages.each do |pkg|
+						pkg.resolved_assets(type).each do |asset|
+							next if seen.include?(asset.id)
+							seen << asset.id
+							arr  << asset
+						end
+					end
+					arr.freeze
+				end
+				block ? @cache[key].each(&block) : @cache[key]
+			end
+
+			def each
+				return to_enum(:each) unless block_given?
+
+				seen = Set.new
+				@database.asset_types.each do |type|
+					each_asset(type).each do |asset|
+						next if seen.include?(asset.id)   # de-dupe across types just in case
+						seen << asset.id
+						yield asset
+					end
+				end
+				self
+			end
+
+		end
+	end
+end

data/lib/asset_db/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AssetDB
+	VERSION = '0.2.0'
+end

data/lib/asset_db.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'set'
+
+# version must come first so errors, etc. have a version constant available
+require_relative 'asset_db/version'
+require_relative 'asset_db/errors'
+require_relative 'asset_db/asset'
+require_relative 'asset_db/group'
+require_relative 'asset_db/package'
+require_relative 'asset_db/resolver'
+require_relative 'asset_db/database'
+
+module AssetDB
+	# DSL entry point, e.g.
+	#
+	#   db = AssetDB.build(types: %i[css js], basepath: '/assets/:type/:group/:package') do |d|
+	#     # ...
+	#   end
+	def self.build(types: nil, basepath: nil, &block)
+		db = Database.new(asset_types: types, basepath: basepath)
+		yield db if block
+		db
+	end
+
+	# Configuration-driven constructor:
+	#
+	#   db = AssetDB.load(config_hash)
+	#
+	def self.load(config)
+		Database.from_config(config)
+	end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: asset_db
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Convincible Media
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-02 00:00:00.000000000 Z
+date: 2025-08-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -60,7 +60,14 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- asset_db.gemspec
+- lib/asset_db.rb
+- lib/asset_db/asset.rb
+- lib/asset_db/database.rb
+- lib/asset_db/errors.rb
+- lib/asset_db/group.rb
+- lib/asset_db/package.rb
+- lib/asset_db/resolver.rb
+- lib/asset_db/version.rb
 homepage: https://github.com/ConvincibleMedia/ruby-gem-assetdb
 licenses:
 - MIT

data/asset_db.gemspec

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-require_relative 'lib/asset_db/version'
-
-Gem::Specification.new do |spec|
-	spec.name          = 'asset_db'
-	spec.version       = AssetDB::VERSION
-	spec.authors       = ['Convincible Media']
-	spec.email         = ['development@convincible.media']
-
-	spec.summary       = "Lightweight asset dependency database for Ruby"
-	spec.description   = "Provides a structured way to define, organise, and resolve assets (CSS, JS, etc.) and their interdependencies across packages and groups."
-	spec.homepage      = 'https://github.com/ConvincibleMedia/ruby-gem-assetdb'
-	spec.license       = 'MIT'
-
-	spec.required_ruby_version = '>= 2.4'
-
-	# Files to include in the gem
-	spec.files = Dir.chdir(__dir__) do
-		`git ls-files -z`.split("\x0").grep(%r{\A(?:lib|README\.md|LICENSE|asset_db\.gemspec)\z})
-	end
-
-	# No runtime dependencies
-	# Development dependencies
-	spec.add_development_dependency 'bundler', '~> 2.0'
-	spec.add_development_dependency 'rake',    '~> 13.0'
-	spec.add_development_dependency 'rspec',   '~> 3.0'
-end