ons-firestore 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 86211db8e2182585d84762f6195444c9558cf20c880cd032dce29184ea166f47
+  data.tar.gz: 26bd51c53071774bba55547accaba38ab32f38dabafb6796949d96a1348c6321
+SHA512:
+  metadata.gz: f3ad8ca48f1f7273285f88e7cbdb1655a25dc999148aadca18552cb510d9058bb7021975ff5da1877ec552c1abbcaaf56b692a41dd21245df780824e9da74179
+  data.tar.gz: ca74cb6ba7a354ba7c0e2808891b75e8ee310fc7d10d96fa3888b5364392a5a710c9512fcae7bd689f39f5a9f2a9fe3a4718dfccce0497adbe867c7f7fd2aabb

data/README.md

@@ -0,0 +1,24 @@
+# ONS Firestore RubyGem
+An opionated abstraction for reading and writing [Google Firestore](https://cloud.google.com/firestore) documents. Note that this gem targets Ruby 3.0 and above.
+
+## Installation
+
+```
+gem install ons-firestore
+```
+
+## Examples
+
+```ruby
+require 'ons-firestore'
+
+firestore = Firestore.new('my-project')
+doc = firestore.read_document('cities', 'London')
+```
+
+## Licence
+
+This library is licensed under the MIT licence. Full licence text is available in [LICENCE](LICENCE).
+
+## Copyright
+Copyright (C) 2022 Crown Copyright (Office for National Statistics)

data/lib/ons-firestore/firestore.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'google/cloud/firestore'
+require 'logger'
+
+# Class to manage access to Firestore.
+class Firestore
+  # Format to use for the timestamp of the +updated+ key within the Firestore document.
+  DATE_TIME_FORMAT = '%A %d %b %Y %H:%M:%S UTC'
+
+  # Constructor that initialises the Firestore client.
+  #
+  # Params:
+  # - project_id: The ID of the GCP project containing the Firestore database.
+  #
+  # An Argument error is raised if project_id is nil.
+  def initialize(project_id)
+    raise ArgumentError.new('project_id cannot be nil') if project_id.nil?
+
+    Google::Cloud::Firestore.configure { |config| config.project_id = project_id }
+    @client = Google::Cloud::Firestore.new
+  end
+
+  # Reads a Firestore document.
+  #
+  # Params:
+  # - collection_name: The name of the Firestore collection containing the document.
+  # - document_name: The name of the Firestore document.
+  #
+  # An Argument error is raised if collection_name or document_name are nil.
+  def read_document(collection_name, document_name)
+    raise ArgumentError.new('collection_name cannot be nil') if collection_name.nil?
+    raise ArgumentError.new('document_name cannot be nil') if document_name.nil?
+
+    document = @client.col(collection_name).doc(document_name)
+    snapshot = document.get
+    snapshot[:data]
+  end
+
+  # Saves a Firestore document, overwriting any existing document with the same name.
+  #
+  # The passed data are saved under a +data+ key within the document.
+  # A timestamp at which the operation occurred is saved under the +updated+ key within the document.
+  #
+  # Params:
+  # - collection_name: The name of the Firestore collection containing the document.
+  # - document_name: The name of the Firestore document.
+  # - data: Data to save to the Firestore document.
+  #
+  # An Argument error is raised if collection_name or document_name are nil.
+  def save_document(collection_name, document_name, data)
+    raise ArgumentError.new('collection_name cannot be nil') if collection_name.nil?
+    raise ArgumentError.new('document_name cannot be nil') if document_name.nil?
+
+    document = @client.col(collection_name).doc(document_name)
+    if data.is_a?(Array)
+      hash_data = []
+      data.each { |element| element.respond_to?(:to_h) ? hash_data << element.to_h : hash_data << element }
+    end
+
+    if data.is_a?(Hash)
+      hash_data = {}
+      data.each do |key, value|
+        hash_data[key] = value.map(&:to_h)
+      end
+    end
+
+    begin
+      document.set({ data: hash_data, updated: Time.now.strftime(DATE_TIME_FORMAT) })
+    rescue StandardError => e
+      logger = Logger.new($stderr)
+      logger.error("Failed to save Firestore document #{document_name} in collection #{collection_name}: #{e.message}")
+      logger.error(e.backtrace.join("\n"))
+    end
+  end
+end

data/lib/ons-firestore/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module ONSFirestore
+  module Version
+    MAJOR = 1
+    MINOR = 0
+    TINY  = 0
+  end
+  VERSION = [Version::MAJOR, Version::MINOR, Version::TINY].compact * '.'
+end

data/lib/ons-firestore.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'ons-firestore/firestore'

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: ons-firestore
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- John Topley
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-04-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: google-cloud-firestore
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+description: 'An opionated abstraction for reading and writing Google Firestore documents.
+
+  '
+email:
+- john.topley@ons.gov.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/ons-firestore.rb
+- lib/ons-firestore/firestore.rb
+- lib/ons-firestore/version.rb
+homepage: https://github.com/ONSdigital/ons-firestore
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.3
+signing_key:
+specification_version: 4
+summary: Opinionated Google Firestore abstraction.
+test_files: []