mindera/alicerce

A base for iOS Applications made with ❤️ by Mindera 🤠

Alicerce 🏗

from Portuguese:

noun • [ masculine ] /ali’sɛɾsɪ/

groundwork, foundation, basis

What is it? 🤔

Ever felt that you keep repeating yourself every time you start a new project? That you would like to have all those useful utils and helpers you love already available? We felt that way too! Thus, Alicerce was born. 🏗

Alicerce is a framework that aims to serve as a starting point for iOS applications, by providing the foundations for many of the common functionalities a modern application requires, as well as be a repository for those small utils and helpers that make our life easier.

It is designed with an MVVM architecture in mind, but you'll find most components are architecture agnostic.

Main features ✨

1. Analytics 🔍
2. Auto Layout 📐
3. Deep Linking 🔗
4. Logging 📝
5. Network 🌍
6. Persistence 💾
7. Performance Metrics 📈
8. Utils ⚙️
9. UI 📲

Documentation 📄

All the documentation can be found in the Documentation folder:

1. Network
2. more coming soon...

Examples 👀

TODO

Compatibility ✅

master

• iOS 13.0+
• Xcode 15.0
• Swift 5.9

0.18.0

• iOS 13.0+
• Xcode 14.0
• Swift 5.7

0.17.0

• iOS 11.0+
• Xcode 14.0
• Swift 5.7

0.16.0

• iOS 10.0+
• Xcode 13.4
• Swift 5.6

0.15.0

• iOS 10.0+
• Xcode 13
• Swift 5.5

0.13.0 ... 0.14.0

• iOS 10.0+
• Xcode 12.5
• Swift 5.4

0.11.0 ... 0.12.0

• iOS 10.0+
• Xcode 12.4
• Swift 5.3

0.9.0 ... 0.10.0

• iOS 10.0+
• Xcode 11.4
• Swift 5.2

0.8.0

• iOS 10.0+
• Xcode 11.0
• Swift 5.1

0.7.0

• iOS 10.0+
• Xcode 10.2
• Swift 5.0

0.6.0

• iOS 9.0+
• Xcode 10.2
• Swift 5.0

0.4.0 ... 0.5.0

• iOS 9.0+
• Xcode 10
• Swift 4.2

0.2.x ... 0.3.0

• iOS 9.0+
• Xcode 9.3
• Swift 4.1

0.1.0

• iOS 9.0+
• Xcode 9
• Swift 4.0

CocoaPods

If you use CocoaPods to manage your dependencies, simply add Alicerce to your Podfile:

pod 'Alicerce', '~> 0.18.0'

Carthage

If you use Carthage to manage your dependencies, simply add Alicerce to your Cartfile:

github "Mindera/Alicerce" ~> 0.18.0

If you use Carthage to build your dependencies, make sure you have added Alicerce.framework to the "Linked Frameworks and Libraries" section of your target, and have included them in your Carthage framework copying build phase.

Swift Package Manager

If you use Swift Package Manager, simply add Alicerce as a dependency of your package in Package.swift:

.package(url: "https://github.com/Mindera/Alicerce.git", from: "0.18.0"),

git Submodule

1. Add this repository as a submodule.
2. Drag Alicerce.xcodeproj into your project or workspace.
3. Link your target against Alicerce.framework.
4. If linking against an Application target, ensure the framework gets copied into the bundle. If linking against a Framework target, the application linking to it should also include Alicerce.

Setup 🛠

Setting up the project for development is simple:

1. Clone the repository.
2. Open Alicerce.xcworkspace
3. Build Alicerce scheme

Contributing 🙌

See CONTRIBUTING.

License ⚖️

Alicerce is Copyright (c) 2016 - present Mindera and is available under the MIT License. It is free software, and may be redistributed under the terms specified in the LICENSE file.

About 👥

With ❤️ from Mindera 🤓

alicerce's Issues

Revise `Equatable` and `Hashable` conformances

Since Swift 4.1 that Equatable and Hashable conformances can be auto synthesized

We currently have some case were we can most likely take advantage of this 💪

Clear `viewModel` on `prepareForReuse` when using `ReusableViewModelView`

As the title implies, should we clear the viewModel on prepareForReuse when inheriting from ReusableViewModelView? With this, we would guarantee that the view/cell is on a pristine state when used again. It should be straightforward to implement as we only need to override prepareForReuse and set the viewModel to nil.

Implement time-to-live (TTL) eviction in `DiskMemoryPersistenceStack`

Even though we intend to break our DiskMemoryPersistenceStack into smaller, more specialized persistence stacks/stores, we should implement a TTL mechanism on the Disk persistence, so that items can be evicted if they are older than X amount of time.

This is useful so that we don't have to just rely on the less frequently used (last accessed time) to evict stale items from the cache.

Use `Result` for asynchronous calls?

When creating Alicerce we agreed that (ideally) it wouldn't have any 3rd party dependency.

Even though we love Result and use it on our projects, this also meant we wouldn't use on Alicerce 😢.

Because of this decision (in great part because of me 😇), we ended up using completion closures with throwing inner closures on our async code (e.g. typealias CompletionClosure<R> = (_ inner: () throws -> R) -> Void), which are hard to write, hard to read, and honestly quite ugly.

While the idea was for framework users to make their own wrappers around these API's using extensions (and we currently do that with ReactiveSwift's SignalProducer, for example), we still have to design and maintain them using this approach, for consistency.

That being said, I am opening up this issue to discuss some possibilities regarding this situation:

1. import Result
2. create our own Result
3. keep things unchanged

Integrate SwiftLint

We should integrate SwiftLint in the project (Xcode build phase and CI), enforcing as many rules as possible from our style guide 💪

Networking examples

Could you please give several networking examples and/or networking stack architecture if possible.

Network Documentation

Hey, it looks like the Network documentation is based on an old version of this framework. To me it looks like that the example RESTResource<T: Codable> class has to implement the RetryableResource protocol. I added conformance to the protocol and the following implementation which I hope is the way to go.

` var retryErrors: [Swift.Error] = []
var totalRetriedDelay: ResourceRetry.Delay = 0
var retryPolicies: [ResourceRetry.Policy<Data, URLRequest, URLResponse>] = []

typealias Request = URLRequest
typealias Response = URLResponse`

If you would confirm this I would love to make PR in order to correct the documentation.

However I am currently searching for a way to authenticate my network stack using OAuth2 (GitHub API). I think this should be fairly easy be possible by using the NetworkAuthenticator and AuthenticationChallengeHandler, but I would love some guidance since I am not quite sure at the moment on how to implement this. Could you help me out here with some information on how to add that to the network stack ?

Add Certificate Pinning on `URLSessionNetworkStack`

Implement a proper server trust validator to allow certificate pinning, and integrate it on URLSessionNetworkStack instead of the very basic AuthenticationChallengeValidatorClosure.

Create submodules / subspecs

Since framework users might only be interested in a subset of the framework's features, it makes sense to allow partial importing.

CocoaPods allows this to be done quite easily by using Subspecs

Carthage seems to have no official support for this (and it might even be against their philosphy)

Perhaps in the future it might make sense to break Alicerce into smaller µFrameworks, because this issue will tend to worsen as we add more functionalities to it 😅

Backtracking on `Route.Tree`'s `match`

Currently, the Route.Tree's match has a limitation where it doesn't fallback (backtrack) to previous possibly valid paths (and thus handlers) when the chosen "matching path" is not completely matched.

Example:

Registered routes:

1. scheme://host/path/one
2. scheme://host/*

Received URL:

• scheme://host/path/two

In this above scenario, the current implementation will fail to match the URL, because when validating the component path it will give priority to the exact match on route no. 1, and when it fails on two (expects one) it will never backtrack to route no. 2 which has a wildcard on the first path component (and should handle the route).

Fixing this limitation will make the Router more robust and allow creating fallbacks and catch-all routes for some scenarios where a specialized handler might not yet be registered.

Expose simple protocol for logger

Shouldn't we expose a simple protocol with just real logging methods?

Our current implementation is:

protocol Logger {

    // MARK:- Destination Management

    func register(_ destination: LogDestination)
    func unregister(_ destination: LogDestination)
    func removeAllDestinations()

    // MARK:- Logging

    func verbose(_ message: @autoclosure () -> String,
                 file: StaticString,
                 function: String,
                 line: UInt)

    func debug(_ message: @autoclosure () -> String,
               file: StaticString,
               function: String,
               line: UInt)

    func info(_ message: @autoclosure () -> String,
              file: StaticString,
              function: String,
              line: UInt)

    func warning(_ message: @autoclosure () -> String,
                 file: StaticString,
                 function: String,
                 line: UInt)

    func error(_ message: @autoclosure () -> String,
               file: StaticString,
               function: String,
               line: UInt)
    
    func log(level: Log.Level,
             message: @autoclosure () -> String,
             file: StaticString,
             function: String,
             line: UInt)
}

but i think we should have a small protocol only with:

public protocol Logger {
    func verbose(_ message: @autoclosure () -> String,
                 file: StaticString,
                 function: String,
                 line: UInt)

    func debug(_ message: @autoclosure () -> String,
               file: StaticString,
               function: String,
               line: UInt)

    func info(_ message: @autoclosure () -> String,
              file: StaticString,
              function: String,
              line: UInt)

    func warning(_ message: @autoclosure () -> String,
                 file: StaticString,
                 function: String,
                 line: UInt)

    func error(_ message: @autoclosure () -> String,
               file: StaticString,
               function: String,
               line: UInt)
}

when using logger, i can create a global instance of Logger and only access the real logging methods and not register, ...

Should use Codable for JSON parsing / encoding

Since Swift 4.0 introduced Codable the library should use it instead of custom JSON parsing via Mappable.

[Resource] Split Resource into small protocols

Problem

Currently the Resource protocol contains all the closures for parse, serialise and error. Probably most of the times those closures aren't used by the implementations and we have to implement it with fatalError.

Solution

Split this in multiple protocols. Any other idea?

This was previously discussed with @p4checo. This is just a reminder so we can discuss this later.

Bringing @danieladias into discussion.

Could you give some example use this frame work?

Some part is hard to understand, if there are any example project will help to use this framework

Add modules/tags to Logging

Currently, our Logging infrastructure doesn't support modules/tags, which are useful in some scenarios, like:

• grouping logs by tag
• filtering logs by tag
• enable/disable logs by tag

The base API should use String for the modules/tags, and then users can create their own extensions using a more type safe API (e.g. using enum MyModule: String).